Skip to content

Latest commit

 

History

History
183 lines (131 loc) · 7.5 KB

CONTRIBUTING.rst

File metadata and controls

183 lines (131 loc) · 7.5 KB
Raw

Contributors' Guide

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.

Getting Started

  • Create a GitHub account if you don't have one already.
  • Search through the 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 post in the GitHub Discussions forum, 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.

Making Changes

  • You can work on bidict in a Visual Studio Code devcontainer environment, where development dependencies and some helpful VS Code extensions are installed inside the dev container environment for you.

    Try Remote-Containers: Clone Repository in Container Volume... on this repository. You may need to reload your VS Code window after it finishes cloning and installing extensions, which it should automatically prompt you to do when you open your clone in VS Code.

    • Note that pre-commit is used to help achieve uniform style and quality standards.

  • If not using a VSCode devcontainer, you can try the following to set up a development environment manually:

    • If you have Nix, you can run nix develop from within your clone to start a shell where all supported Python versions as well as pre-commit are installed and added to your PATH.

      Otherwise, manually ensure you have pre-commit and at least the latest stable Python version installed and on your PATH.

    • Run ./init_dev_env

      This installs the git hooks for pre-commit in your clone, creates a virtualenv with all the development dependencies installed, and reminds you to activate the virtualenv env it just created when ready.

  • Create a topic branch off of main for your changes: git checkout -b <topic> main

  • 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 envlist in tox.ini for 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 GitHub Actions build, which should run the tests for all supported Python versions. Testing your changes with GitHub Actions will require approval from a project admin the first time you submit a PR.

  • 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.

Submitting Changes

  • 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.

Sponsoring

Sponsor through GitHub Sponsor through PayPal

Bidict is the product of thousands of hours of my unpaid work over the 15+ years that I've been the sole maintainer.

If bidict has helped you or your company accomplish your work, please sponsor my work through one of the following, and/or ask your company to do the same:

If you're not sure which to use, GitHub is an easy option, especially if you already have a GitHub account. Just choose a monthly or one-time amount, and GitHub handles everything else. Your bidict sponsorship on GitHub will automatically go on the same regular bill as any other GitHub charges you pay for. PayPal is another easy option for one-time contributions.

See the following for rationale and examples of companies supporting the open source projects they depend on in this manner:

Code of Conduct

All participation in this project should respect the code-of-conduct. [1]

By participating, you are expected to honor this code.

[1]https://bidict.readthedocs.io/code-of-conduct.html | CODE_OF_CONDUCT.rst