Contributing to this project

Checklist

  1. All potential contributors must read the Contributor Code of Conduct and follow it

  2. Fork the repository on GitHub or GitLab

  3. Create a new branch, e.g., git checkout -b bug/12345

  4. Fix the bug and add tests (if applicable 1, see How To Add Tests)

  5. Run the tests (see How To Run The Tests below)

  6. Add documentation (as necessary) for your change

  7. Build the documentation to check for errors and formatting (see How To Build The Documentation below)

  8. Add yourself to the AUTHORS.rst (unless you’re already there)

  9. Commit it. Follow these rules in your commit message:

    • Keep the subject line under 50 characters

    • Use an imperative verb to start the commit

    • Use an empty line between the subject and the message

    • Describe the why in detail in the message portion of the commit

    • Wrap the lines of the message at 72 characters

    • Add the appropriate “Closes #12345” syntax to autoclose the issue it fixed (if it closes an issue)

    • See Example Commit Message below

  10. Push it to your fork

  11. Create a request for us to merge your contribution

After this last step, it is possible that we may leave feedback in the form of review comments. When addressing these comments, you can follow two strategies:

  • Amend/rebase your changes into an existing commit

  • Create a new commit with a different message 2 describing the changes in that commit and push it to your branch

This project is not opinionated about which approach you should prefer. We only ask that you are aware of the following:

  • Neither GitHub nor GitLab notifies us that you have pushed new changes. A friendly ping is encouraged

  • If you continue to use the same branch that you created the request from, both GitHub and GitLab will update the request on the website. You do not need to create a new request for the new changes.

Contributor Code of Conduct

As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

Examples of unacceptable behavior by participants include:

  • The use of sexualized language or imagery

  • Personal attacks

  • Trolling or insulting/derogatory comments

  • Public or private harassment

  • Publishing other’s private information, such as physical or electronic addresses, without explicit permission

  • Other unethical or unprofessional conduct

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.

This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a project maintainer at graffatcolmingov@gmail.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident.

This Code of Conduct is adapted from the Contributor Covenant, version 1.3.0, available at http://contributor-covenant.org/version/1/3/0/

How To Add Tests

We use pytest to run tests and to simplify how we write tests. If you’re fixing a bug in an existing please find tests for that module or feature and add to them. Most tests live in the tests directory. If you’re adding a new feature in a new submodule, please create a new module of test code. For example, if you’re adding a submodule named foo then you would create tests/test_foo.py which will contain the tests for the foo submodule.

How To Run The Tests

Run the tests in this project using tox. Before you run the tests, ensure you have installed tox either using your system package manager (e.g., apt, yum, etc.), or your prefered python installer (e.g., pip).

Then run the tests on at least Python 2.7 and Python 3.x, e.g.,

$ tox -e py27,py34

Finally run one, or both, of the flake8 style enforcers, e.g.,

$ tox -e py27-flake8
# or
$ tox -e py34-flake8

It is preferable if you run both to catch syntax errors that might occur in Python 2 or Python 3 (based on how familiar you are with the common subset of language from both).

Tox will manage virtual environments and dependencies for you so it will be the only dependency you need to install to contribute to this project.

How To Build The Documentation

To build the docs, you need to ensure tox is installed and then you may run

$ tox -e docs

This will build the documentation into docs/_build/html. If you then run

$ python2.7 -m SimpleHTTPServer
# or
$ python3.4 -m http.server

from that directory, you can view the docs locally at http://localhost:8000/.

Example Commit Message

Allow users to use the frob when uploading data

When uploading data with FooBar, users may need to use the frob method
to ensure that pieces of data are not munged.

Closes #1234567

Footnotes

1

You might not need tests if you’re updating documentation, fixing a typo, or updating a docstring. If you’re fixing a bug, please add tests.

2

If each commit has the same message, the reviewer may ask you to squash your commits or may squash them for you and perform a manual merge.