Contributing Guide

Happy baking!

Set up development environment

git clone https://github.com/font-bakers/knead.git
cd knead/
make develop
source venv/bin/activate
# Do your work...
deactivate

Before committing

make check

This will both lint the knead/ directory (with black and pylint), and run test scripts. You may lint and test separately with make lint and make test, respectively.

Make sure that all checks pass before committing: you should get several blue success messages as each check passes.

Note that knead uses a pre-commit git hook to format staged Python files in-place using black.

Packaging and releasing knead

First, ensure that the version number has been bumped appropriately:knead adopts the Semantic Versioning 2.0.0 specification. This can be done either by running

bumpversion --current-version CURRENT_VERSION PART knead/__init__.py

or by directly editing the __version__ variable in knead/__init__.py (the latter method is simpler and recommended for such a simple project as knead). For more information, see the bumpversion documentation.

Then, run make package. It will package knead and validate the resulting source archive and built distribution.

Finally, upload the source archive and build distribution to PyPI. You will be asked for a username and password for PyPI.

twine upload dist/*

For more information, refer to the Python packaging documentation.

Miscellaneous development details

• knead adopts the Semantic Versioning 2.0.0 specification.

• knead targets Python 3.5+ (specifically, 3.5.2+) compatibility.

• knead uses black and pylint to format and lint code, respectively.

• However, black requires Python 3.6+ to run. Thus, we test in Python 3.5 but lint in Python 3.6. See our Travis configuration for more details.

• knead contains integration tests in the form of the test.sh script. knead is currently not unit tested.

• Briefly, test.sh first hashes the data/ directory (using the shasum command line tool). It then runs the entire data pipeline, conversion by conversion, on one font (Georgia.ttf). After every conversion, the data/ directory is hashed again. If the hash differs from the initial hash, the test fails. In this way, we test the knead output for correctness.

• This is not possible for .pb files, which change after every write. Thus, we merely count the number of .pb files that are generated.

• The knead documentation is generated using mkdocs. See the mkdocs.yml configuration for more details.