Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Note

The commands below are presumed to be run relative to the project root unless explicitly stated otherwise. ./ also refers to the project root.

Ways You Can Help Us

Report Bugs

Create an issue corresponding to the bug you have found complying with the project’s issue template.

Fix Bugs

Look through the GitHub issues: Anything tagged with bug and without an Assignee is open to whoever wants to implement it.

Make sure to submit clean, concise, well-tested pull requests only, so it is easier for contributors to review it; strive to deliver as short and atomic pull requests as possible as this will dramatically increase the likelihood of those being merged.

Implement Features

Look through the GitHub issues for features. Anything tagged with enhancement and/or help wanted and/or without an Assignee is open to whoever wants to implement it.

Write Documentation

We could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue.

If you are proposing a feature,

  • explain in detail how it would work;
  • keep the scope as narrow as possible, to make it easier to implement;
  • remember that this is a volunteer-driven project, so contributions are welcome!

Workflow

See Developing Locally for detailed instructions on setting up local environment.

Oncer you are all set up,

  1. create a branch:

    $ git checkout -b <issue id>-<issue title>
    
  2. make the contribution;

  3. follow Running tox with Multiple Python Distributions to run tests comprehensively;

  4. commit changes to the branch:

    $ git add .
    $ git commit -m "<detailed description of your changes>"
    
  5. push the branch to GitHub:

    $ git push origin <issue id>-<issue title>
    
  6. submit a pull request via GitHub or any other git GUI tool you prefer.

Guidelines

Upon submission, make sure the PR meets these guidelines:

  1. the PR does not decrease code coverage (unless there is a very specific reason to);
  2. the docs (both programmatic and manual) are updated, if needed.