From d6b8bd464cb032e8180b4219d9821cb3cf8e3d89 Mon Sep 17 00:00:00 2001 From: David Pursehouse Date: Sat, 15 Feb 2020 13:51:17 +0900 Subject: [PATCH] Reword the documentation regarding coding style - flake8 is a wrapper around pyflakes, so it's redundant to mention both of them. Roll the explicit sections about coding errors and coding style violations into a single section. - After recent cleanups the project now has zero warnings or errors from flake8. Reword the requirements so that it is now mandatory to not introduce new warnings. - Expand the section on suppression of warnings to differentiate between suppressing inline individually and globally suppressing for the whole project. - Properly capitalize "Python Style Guide". Change-Id: I4b333d013e985db252873441b16cb719ed5be5b5 Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/255040 Tested-by: David Pursehouse Reviewed-by: Mike Frysinger --- SUBMITTING_PATCHES.md | 35 +++++++++++++---------------------- 1 file changed, 13 insertions(+), 22 deletions(-) diff --git a/SUBMITTING_PATCHES.md b/SUBMITTING_PATCHES.md index 316cb62..c51fac0 100644 --- a/SUBMITTING_PATCHES.md +++ b/SUBMITTING_PATCHES.md @@ -4,7 +4,7 @@ - Make small logical changes. - Provide a meaningful commit message. - - Check for coding errors and style nits with pyflakes and flake8 + - Check for coding errors and style nits with flake8. - Make sure all code is under the Apache License, 2.0. - Publish your changes for review. - Make corrections if requested. @@ -38,39 +38,30 @@ If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces. -## Check for coding errors and style nits with pyflakes and flake8 +## Check for coding errors and style violations with flake8 -### Coding errors - -Run `pyflakes` on changed modules: - - pyflakes file.py - -Ideally there should be no new errors or warnings introduced. - -### Style violations - -Run `flake8` on changes modules: +Run `flake8` on changed modules: flake8 file.py -Note that repo generally follows [Google's python style guide] rather than +Note that repo generally follows [Google's Python Style Guide] rather than [PEP 8], with a couple of notable exceptions: * Indentation is at 2 columns rather than 4 * The maximum line length is 100 columns rather than 80 -It's possible that the output of `flake8` will be quite noisy, so it's not -mandatory to avoid all warnings, but at least the maximum line length -should be followed. +There should be no new errors or warnings introduced. -If there are many occurrences of the same warning that cannot be -avoided without going against the Google style guide, these may be -suppressed in the included `.flake8` file. +Warnings that cannot be avoided without going against the Google Style Guide +may be suppressed inline individally using a `# noqa` comment as described +in the [flake8 documentation]. -[Google's python style guide]: https://google.github.io/styleguide/pyguide.html +If there are many occurrences of the same warning, these may be suppressed for +the entire project in the included `.flake8` file. + +[Google's Python Style Guide]: https://google.github.io/styleguide/pyguide.html [PEP 8]: https://www.python.org/dev/peps/pep-0008/ - +[flake8 documentation]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors ## Running tests