Fix some typos and reword some bits in README and CONTRIBUTING
This commit is contained in:
+19
-23
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user