Fix some typos and reword some bits in README and CONTRIBUTING

This commit is contained in:
Veronica K. B. Olsen
2021-01-23 13:14:50 +01:00
parent 6f84574511
commit 3f8c705989
2 changed files with 39 additions and 42 deletions
+19 -23
View File
@@ -1,10 +1,9 @@
# Contributing Guide
When contributing to this repository, please first discuss the change you wish to make via the
issue tracker with the owner of this repository before making a change. If you just want to make a
minor correction, like fix a typo or similar, feel free to just make a pull request directly.
There is a code of conduct. Please follow it in all your interactions with the project.
issue tracker or the discussions page with the owner of this repository before making a change. If
you just want to make a minor correction, like fix a typo or similar, feel free to just make a pull
request directly.
## Pull Request Process
@@ -13,11 +12,13 @@ There is a code of conduct. Please follow it in all your interactions with the p
2. Please provide a complete description of the changes in the pull request, and a summary that can
be copied into the [CHANGELOG](CHANGELOG.md). Remember to reference any issue related by
providing the issue number.
3. Do not change the version number unless asked to do so. Version numbers are bumped in separate
release pull requests by the maintainer.
3. Do not change the version number. Version numbers are bumped in separate release pull requests
by the maintainer.
## Code of Conduct
There is a code of conduct. Please follow it in all your interactions with the project.
### Our Pledge
In the interest of fostering an open and welcoming environment, we as contributors and maintainers
@@ -31,7 +32,7 @@ Please see the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) file for the full text.
## Code Style Guide
The source code of novelWriter broadly follows the [PEP8](https://www.python.org/dev/peps/pep-0008)
style guide , but with a few modifications and exceptions.
style guide, but with a few modifications and exceptions listed below.
### Line Length
@@ -39,20 +40,21 @@ For this project, source lines should stay within the 79 and 99 character limits
79 characters is often too restrictive, so 99 character lines are acceptable when that is more
practical. Readability has priority. Generally, if a code statement requires multiple lines, the
lines should wrap at 79 characters, not 99. If wrapping can be avoided by going to 99, then that is
preferrable.
generally preferrable.
For text files, the text should also be wrapped at 99 character. The exception is markdown image
tags and urls.
Please do not submit PRs that re-wrap existing source or text unless this has been discussed
beforehand.
Please do not submit pull requests that re-wrap existing source or text unless this has been
discussed beforehand.
### Linting with flake8
### Linting with `flake8`
An excellent tool for checking Python code for errors and coding style is `flake8`. The
documentation is available [here](https://flake8.pycqa.org/en/latest/).
The `setup.cfg` file in the root of this project has the following settings:
The `setup.cfg` file in the root of this project has the following settings for `flake8` that
matches the coding standard:
```conf
[flake8]
ignore = E203,E221,E226,E228,E241,E251,E261,E266,E302,E305
@@ -73,23 +75,17 @@ not conform to the standard.
## Ignored Errors
Some `flake8` error codes are ignored for this project for various reasons. The source also uses
camelCase function and variable names due to this being the standard for the Qt libraries, and also
because of the author's personal preferences.
camelCase function and variable names. This is the standard for the Qt libraries novelWriter
integrates with. It also happens to be the author's personal preferences.
The reason behind the other ignored error codes are listed below. Many of them are due to PEP8 not
permitting column alignment as opposed to many other coding styles. I find them useful in regions
of bulk value assignments. There's a reason why tables are more readable than lists. They should be
used sparingly though.
permitting column alignment as opposed to many other coding styles, like for instance for Go. I
find them useful in regions of bulk value assignments. There's a reason why tables are more
readable than lists. They should be used sparingly though.
The ignored errors are all `pycodestyle` errors, and they are documented
[here](https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes).
My main objection to PEP8 is the universal rejection of column alignment of blocks of code. In
particular when assigning variables and populating dictionaries. The PEP8 rule stands in contrast
to conventions from other code styles, like for Go. I have always used column alignment to a
certain degree in all programming languages I use, and I firmly believe it improves readability,
but should not be overused.
**E203:** whitespace before :
**Reason:** Column alignment.