mirror of https://github.com/jab/bidict.git
186 lines
7.3 KiB
ReStructuredText
186 lines
7.3 KiB
ReStructuredText
.. Forward declarations for all the custom interpreted text roles that
|
|
Sphinx defines and that are used below. This helps Sphinx-unaware tools
|
|
(e.g. rst2html, PyPI's and GitHub's renderers, etc.).
|
|
.. role:: doc
|
|
.. role:: ref
|
|
|
|
|
|
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 <https://github.com/join>`__ if you don't have one
|
|
already.
|
|
|
|
- Search through the `tracker <https://github.com/jab/bidict/issues?q=>`__
|
|
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 <https://gitter.im/jab/bidict>`__ to discuss there,
|
|
post in the `GitHub Discussions forum <https://github.com/jab/bidict/discussions>`__,
|
|
or go ahead and `create a new issue <https://github.com/jab/bidict/issues/new>`__:
|
|
|
|
- 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 <https://github.com/jab/bidict/fork>`__
|
|
and have cloned it to your computer.
|
|
|
|
|
|
Making Changes
|
|
--------------
|
|
|
|
.. note:: You can now use
|
|
`GitPod.io <https://gitpod.io/#https://github.com/jab/bidict>`__
|
|
to get an already-configured development environment inside your browser
|
|
in which you can make, test, and submit your changes to bidict.
|
|
|
|
.. note:: You can also work on bidict in a Visual Studio Code
|
|
`devcontainer environment <https://code.visualstudio.com/docs/remote/containers>`__
|
|
which will install development dependencies and some helpful VS Code
|
|
extensions 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 prompt you to do.
|
|
|
|
In a devcontainer, you don't need to worry about the below steps of making a
|
|
virtualenv or configuring EditorConfig or pre-commit, those will be part of
|
|
your development environment by default.
|
|
|
|
- Before making changes, please
|
|
(create a `virtualenv <http://virtualenv.pypa.io>`__ and)
|
|
install the extra packages required for development
|
|
if you haven't already:
|
|
``pip install -r requirements/test.txt -r requirements/lint.txt -r requirements/docs.txt``
|
|
|
|
We use `EditorConfig <https://editorconfig.org/>`__
|
|
and `pre-commit <https://pre-commit.com/>`__
|
|
to help achieve uniform style and quality standards
|
|
across a diversity of development environments.
|
|
|
|
pre-commit gets installed when you run the command above
|
|
and ensures that various code checks are run before every commit
|
|
(look in ``.pre-commit-config.yaml`` to see which hooks are run).
|
|
Ensure the configured hooks are installed by running
|
|
``pre-commit install --install-hooks``.
|
|
|
|
EditorConfig allows us to provide a single ``.editorconfig`` file
|
|
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 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 <https://tox.readthedocs.io>`__
|
|
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 <https://github.com/jab/bidict/actions>`__ build,
|
|
which should run the tests for all supported Python versions.
|
|
|
|
- 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
|
|
----------
|
|
|
|
.. image:: https://img.shields.io/badge/GitHub-sponsor-ff69b4
|
|
:target: https://github.com/sponsors/jab
|
|
:alt: Sponsor through GitHub
|
|
|
|
.. image:: https://img.shields.io/badge/Gumroad-sponsor-55a0a4.svg
|
|
:target: https://gumroad.com/l/bidict
|
|
:alt: Sponsor through Gumroad
|
|
|
|
.. image:: https://img.shields.io/badge/PayPal-sponsor-blue.svg
|
|
:target: https://www.paypal.com/cgi-bin/webscr?cmd=_xclick&business=jabronson%40gmail%2ecom&lc=US&item_name=Sponsor%20bidict
|
|
:alt: Sponsor through PayPal
|
|
|
|
.. image:: https://img.shields.io/github/sponsors/jab
|
|
:target: https://github.com/sponsors/jab
|
|
:alt: Sponsors on GitHub
|
|
|
|
.. duplicated in README.rst
|
|
(would use `.. include::` but GitHub doesn't understand it)
|
|
|
|
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 GitHub <https://github.com/sponsors/jab>`__,
|
|
and/or ask your company to do the same.
|
|
|
|
Choose a tier and GitHub handles everything else.
|
|
Your GitHub sponsorship will automatically go
|
|
on the same bill you already have set up with GitHub,
|
|
so after the one-click signup, there's nothing else to do.
|
|
|
|
You can also sponsor my work through
|
|
`Gumroad <https://gumroad.com/l/bidict>`__ or
|
|
`PayPal <https://www.paypal.com/cgi-bin/webscr?cmd=_xclick&business=jabronson%40gmail%2ecom&lc=US&item_name=Sponsor%20bidict>`__,
|
|
or through a support engagement with my LLC.
|
|
See `Enterprise Support
|
|
<https://bidict.readthedocs.io/#enterprise-support>`__
|
|
for details.
|
|
|
|
|
|
Code of Conduct
|
|
---------------
|
|
|
|
All participation in this project should respect the
|
|
:doc:`code-of-conduct`. [#fn-coc]_
|
|
|
|
By participating, you are expected to honor this code.
|
|
|
|
.. [#fn-coc] `<https://bidict.readthedocs.io/code-of-conduct.html>`__ | `<CODE_OF_CONDUCT.rst>`__
|