How to contribute

Tutorials

If you want to start working on this project, you will need to get familiar with these APIs:

• Writing a flake8 plugin

• Using ast module

• Tokenizer for Python source

It is also recommended to take a look at these resources:

• Visual tool to explore python’s ast (very useful!)

• Missing ast guide

• List of python static analysis tools

• List of flake8 extensions

Developer’s documentation

Make sure that you are familiar with developer’s documentation.

That’s a main starting point to the future development. You can jump start into the development of new rules by reading “Creating a new rule tutorial”.

Dependencies

We use poetry to manage the dependencies.

To install them you would need to run install command:

poetry install

To activate your virtualenv run poetry shell.

Adding new flake8 plugins

If you are adding a flake8 plugin dependency (not dev-dependency), you will have to do several things:

1. Install plugin with poetry

2. Add docs about the error code to the pages/usage/violations/index.rst

3. Add a test that the plugin is working to tests/test_plugins.py

One magic command

Run make test to run everything we have!

Tests

We use pytest and flake8 for quality control. We also use wemake_python_styleguide itself to develop wemake_python_styleguide.

To run all tests:

pytest

To run linting:

flake8 .

These steps are mandatory during the CI.

Architecture

We use import-linter to enforce strict layered architecture.

lint-imports

See .importlinter file for contracts definition. All contracts must be valid for each commit. This step is mandatory during the CI.

Type checks

We use mypy to run type checks on our code. To use it:

mypy wemake_python_styleguide

This step is mandatory during the CI.

Helpers

We also have several helpers to make your development work easier:

• ./scripts/parse.py is used to visualize ast nodes in other python modules, usage: python ./scripts/parse.py my_module.py

• ./scripts/tokens.py is used to visualize tokens in other python modules, usage: python ./scripts/tokens.py my_module.py

Submitting your code

We use trunk based development (we also sometimes call it wemake-git-flow).

What the point of this method?

1. We use protected master branch, so the only way to push your code is via pull request

2. We use issue branches: to implement a new feature or to fix a bug create a new branch named issue-$TASKNUMBER

3. Then create a pull request to master branch

4. We use git tags to make releases, so we can track what has changed since the latest release

So, this way we achieve an easy and scalable development process which frees us from merging hell and long-living branches.

In this method, the latest version of the app is always in the master branch.

Before submitting

Before submitting your code please do the following steps:

1. Run pytest to make sure everything was working before

2. Add any changes you want

3. Add tests for the new changes

4. Add an integration test into tests/fixtures/noqa.py

5. Edit documentation if you have changed something significant

6. Update CHANGELOG.md with a quick summary of your changes

7. Run pytest again to make sure it is still working

8. Run mypy to ensure that types are correct

9. Run flake8 to ensure that style is correct

10. Run lint-imports to ensure that architecture contracts are correct

11. Run doc8 to ensure that docs are correct

12. Run xenon to ensure that code quality is A (good enough)

You can run everything at once with make test, see our Makefile for more details.

Notes for maintainers

This section is intended for maintainers only. If you are not a maintainer (or do not know what it means), just skip it. You are not going to miss anything useful.

Making patches to older versions

If you want to release a patch for an older version, that what you have to do:

1. Check out the previous tag

2. Create a new branch relative to this tag: git checkout $TAG_NAME; git checkout -b $RELEASE_NAME

3. Merge it into master, there might be some rebase and cherry-pick involved during this operation

Other help

You can contribute by spreading a word about this library. It would also be a huge contribution to write a short article on how you are using this project. You can also share your best practices with us.

You can also consider donations to the project:

• https://opencollective.com/wemake-python-styleguide

• https://issuehunt.io/r/wemake-services/wemake-python-styleguide

Number of current supporters:

List of contributors

Here are the awesome people who contributed to our project: