Skip to content

Contributing to dyce

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

Starting discussions and 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.

For more free-flow discussions (beefs, rants, ideas, recipes, etc.), consider starting or joining a discussion.

Hacking quick-start

An easy way to bootstrap an isolated development environment is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
% git clone --recurse-submodules https://github.com/posita/dyce.git
…
% cd dyce
% /path/to/python -m venv .venv
…
% . .venv/bin/activate
% pip install --upgrade --editable '.[dev]'
…
% python -m pre_commit install
…

Substitute your preferred virtual environment process for venv. The [dev] variant includes additional dependencies necessary for development and testing. See the [options.extras_require] section in setup.cfg.

Unit tests are run with pytest via Tox.

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

Special considerations for regenerating class diagrams

We use Pyreverse to generate class diagrams. Pyreverse is not very flexible with respect to what it includes. We use PyGraphviz to get rid of unwanted entries from the .dot file generated by Pyreverse. This is because the pure-Python alternative we use elsewhere does not support editing. PyGraphviz has some special needs when it comes to installation.

This dumpster fire is complicated and fragile.1 Depending on your configuration, PyGraphviz may not be able to find the native Graphviz library it needs. This can often be remedied by setting the appropriate gcc environment variables.

1
CPATH=/opt/local/include LIBRARY_PATH=/optlocal/lib tox -e check-classdiagrams

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.

  1. It is uncanny how often those two properties are found together. ↩