From 1f5e4e221ec1131331a9c5054efc85e4281c3d19 Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sat, 15 May 2021 07:33:14 +0300 Subject: Reorganizes Contributing Guidelines Drops mentions of black, renames mentions of precommit to pre-commit, and rewords statements that have caused confusion. --- .../apps/content/resources/guides/pydis-guides/contributing.md | 1 + .../pydis-guides/contributing/contributing-guidelines.md | 3 ++- .../contributing-guidelines/supplemental-information.md | 10 ++++++---- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index f8baa354..d367dbc7 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -95,6 +95,7 @@ If you don't understand anything or need clarification, feel free to ask any sta ### Useful Resources +[Guidelines](./contributing-guidelines/) - General guidelines you should follow when contributing to our projects.
[Style Guide](./style-guide/) - Information regarding the code styles you should follow when working on our projects.
[Review Guide](../code-reviews-primer/) - A guide to get you started on doing code reviews. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md index aa784a50..de1777f2 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md @@ -15,7 +15,8 @@ If you are confused by any of these rules, feel free to ask us in the `#dev-cont 1. **Lint before you push.** We have simple but strict style rules that are enforced through linting. You must always lint your code before committing or pushing. -[Using tools](./supplemental-information/#linting-and-precommit) such as `precommit` or `black` can make this easier. +[Using tools](./supplemental-information/#linting-and-pre-commit) such as `flake8` and `pre-commit` can make this easier. +Make sure to follow our [style guide](../style-guide/) when contributing. 2. **Make great commits.** Great commits should be atomic, with a commit message explaining what and why. More on that can be found in [this section](./supplemental-information/#writing-good-commit-messages). diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md index 78a27173..c5c63c96 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md @@ -25,20 +25,22 @@ During PR review, it's not unusual for style adjustments to be requested. [This page](../../style-guide/) will reference the differences between our projects and what is recommended by [PEP 8.](https://www.python.org/dev/peps/pep-0008/) -## Linting and Precommit +## Linting and Pre-commit -On most of our projects, we use `flake8` and `precommit` to ensure that the code style is consistent across the code base. +On most of our projects, we use `flake8` and `pre-commit` to ensure that the code style is consistent across the code base. Running `flake8` will warn you about any potential style errors in your contribution. You must always check it **before pushing**. Your commit will be rejected by the build server if it fails to lint. -`precommit` is a powerful tool that helps you automatically lint before you commit. +**Some style rules are not enforced by flake8. Make sure to read the [style guide](../../style-guide/).** + +`pre-commit` is a powerful tool that helps you automatically lint before you commit. If the linter complains, the commit is aborted so that you can fix the linting errors before committing again. That way, you never commit the problematic code in the first place! Please refer to the project-specific documentation to see how to setup and run those tools. -In most cases, it is either `pipenv run [lint | precommit]` or `poetry run [lint | precommit]`. +In most cases, you can install pre-commut using `pipenv run precommit` or `poetry run task precommit`, and lint using `pipenv run lint` or `poetry run task lint`. ## Type Hinting -- cgit v1.2.3