Bug reports, feature requests, patches, and other contributions are warmly welcomed. Contribution should be as easy and friendly as possible. Below are a few guidelines contributors should follow to facilitate the process.
Create a GitHub account if you don’t have one already.
Search through the issue tracker to see if an issue or pull request has already been created for what you’re interested in. If so, feel free to add comments to it or just hit the “subscribe” button to follow progress. If not, you can join the chat room to discuss there, or go ahead and create a new issue:
Clearly describe the issue giving as much relevant context as possible.
If it is a bug, include reproduction steps, all known environments in which the bug is exhibited, and ideally a failing test case.
If you would like to contribute a patch, make sure you’ve created your own fork and have cloned it to your computer.
Before making changes, please install the extra packages required for development:
pip install -e .[dev]
pre-commit gets installed when you run
pip install -e .[dev]and ensures that various code checks are run before every commit (look in
.pre-commit-config.yamlto see which hooks are run).
EditorConfig allows us to provide a single
.editorconfigfile to configure settings like indentation consistently across a variety of supported editors. See https://editorconfig.org/#download to install the plugin for your editor.
Create a topic branch off of master for your changes:
git checkout -b <topic> master
Make commits of logical units.
Match the existing code style and quality standards. If you’re adding a feature, include accompanying tests and documentation demonstrating its correctness and usage.
Run the tests locally with tox to make sure they pass for all supported Python versions (see
tox.inifor the complete list). If you do not have all the referenced Python versions available locally, you can also push the changes on your branch to GitHub to automatically trigger a new Travis-CI build, which should run the tests for all supported Python versions. You should be able to see the results at
<user>is the GitHub username you used to fork bidict.
Create a concise but comprehensive commit message in the following style:
Include an example commit message in CONTRIBUTING guide #9999 Without this patch the CONTRIBUTING guide would contain no examples of a model commit message. This is a problem because the contributor is left to imagine what the commit message should look like and may not get it right. This patch fixes the problem by providing a concrete example. The first line is an imperative statement summarizing the changes with an issue number from the tracker. The body describes the behavior without the patch, why it's a problem, and how the patch fixes the problem.
Push your changes to a topic branch in your fork of the repository:
git push --set-upstream origin <topic>
Submit a pull request providing any additional relevant details necessary.
Acknowledgment should typically be fast but please allow 1-2 weeks for a full response / code review.
The code review process often involves some back-and-forth to get everything right before merging. This is typical of quality software projects that accept patches.
All communication should be supportive and appreciative of good faith efforts to contribute, creating a welcoming and inclusive community. Expect nothing less of any project.
Other Ways to Contribute¶
Bidict is the product of hundreds of hours of unpaid, voluntary work.
If bidict has helped you accomplish your work, especially work you’ve been paid for, please consider chipping in toward the costs of bidict’s maintenance and development and/or ask your organization to do the same. Any amount contributed is gratefully received.
Besides chipping in financially, filing issues, and submitting pull requests, there are other ways to contribute.
If you’re using bidict in a project you work on, please post about your experience and send me a link.
If you come across other people who could find bidict useful, please spread the word.
Please support bidict: