Skip to content

Contributing to dyce

There are many ways you can contribute. You have only but to try.

Filing issues

You can file new issues as you find them. Please try to avoid duplicating issues. “Writing Effective Bug Reports” by Elisabeth Hendrickson (PDF) may be helpful.

Hacking quick-start

A helper script is provided for bootstrapping an isolated development environment.

1
2
3
% [PYTHON=…/path/to/python] helpers/venvsetup.sh
…
% . .venv/bin/activate

The helper script is really only there to help folks get their feet wet who don’t already manage their own virtual environments. The above is essentially equivalent to the following (with some additional checking).

1
2
3
4
5
% …/path/to/python -m virtualenv .venv || …/path/to/python -m venv .venv
…
% .venv/bin/pip install --upgrade --editable '.[dev]'
…
% . .venv/bin/activate

The [dev] variant includes additional dependencies necessary for development and testing. See the extras_require parameter in setup.py.

Unit tests are run with Tox (but can also be run with pytest directly, if installed).

1
2
3
4
5
6
% cd …/path/to/dyce
% . .venv/bin/activate
% tox [TOX_ARGS... [-- PYTEST_ARGS...]]
…
% pytest [PYTEST_ARGS...]
…

A bare bones example:

1
2
3
4
5
6
% git clone https://github.com/posita/dyce.git  # or your fork
% cd dyce
% helpers/venvsetup.sh && . .venv/bin/activate
…
% tox
…

A virtualenvwrapper-based alternative:

1
2
3
4
5
6
7
% git clone https://github.com/posita/dyce.git  # or your fork
% mkvirtualenv [--python=…/path/to/python] -a "${PWD}/dyce" dycelib
…
% pip install --upgrade --editable '.[dev]'
…
% tox
…

Submission guidelines

If you are willing and able, consider submitting a pull request with a fix. See the docs if you’re not already familiar with pull requests. dyce releases from master (although not always immediately), so a lot of these workflows are helpful. There are only a few additional guidelines:

  • If it is not already present, please add your name (and optionally your email, GitHub username, website address, or other contact information) to the LICENSE file.
1
2
3
...
* [Matt Bogosian](mailto:matt@bogosian.net?Subject=dyce); GitHub – [**@posita**](https://github.com/posita)
...

  • Use Black to format your changes. Do your best to follow the source conventions as you observe them. If it’s important to you, Existing comments are wrapped at 88 characters per line to match Black’s default. (Don’t spend too much effort on strict conformance, though. I can clean things up later if they really bother me.)

  • Provide tests where feasible and appropriate. At the very least, existing tests should not fail. (There are exceptions, but if there is any doubt, they probably do not apply.) Unit tests live in tests.

  • If you want feedback on a work-in-progress, consider “mentioning” me (@posita), and describe specifically how I can help. Consider prefixing your pull request’s title with something like, “NEED FEEDBACK –”.

  • If your pull request is still in progress, but you are not blocked on anything, consider using the draft feature.

  • Once you are ready for a merge, resolve any conflicts, squash your commits, and provide a useful commit message. (This and this may be helpful.) If your pull request started out as a draft, promote it by requesting a review. Consider prefixing the pull request’s title to something like, “READY FOR MERGE –”. I will try to get to it as soon as I can.