Contributing

Thank you for considering contributing to Mold! If you’ve found a bug or would like to propose a feature, please submit an issue.

If you’d like to get more involved, here’s how. There are many valuable contributions in addition to contributing code! If you’re so inclined, triaging issues, improving documentation, helping other users and reviewing existing code and PRs is equally appreciated!

The rest of this guide focuses on development and code contributions.

Installation

Start by cloning the most recent version, either from the main repository or a fork you created, and installing the source as an editable package. Using a virtual environment of your choice for the installation is recommended.

$ git clone https://github.com/felix-hilden/mold.git
$ cd mold
$ pip install -e .[dev]

The last command installs all the necessary extra dependencies for development.

If you forked, consider adding the upstream repository as a remote to easily update your main branch with the latest upstream changes. For tips and tricks on contributing, see how to submit a contribution, specifically opening a pull request.

Testing

The install can be verified, and any changes tested by running tox.

$ tox

Now tests and static checks have been run. A list of all individual tasks can be viewed with their descriptions.

$ tox -a -v

Test suite

The repository contains a suite of test cases which can be studied and run to ensure the package works as intended.

$ pytest

For tox, this is the default command when running e.g. tox -e py. To measure test coverage and view uncovered lines or branches run coverage.

$ coverage run
$ coverage report

This can be achieved with tox by running tox -e coverage.

Documentation

Documentation can be built locally with Sphinx.

$ cd docs
$ make html

The main page index.html can be found in build/html.

Code style

A set of style rules is followed using a variety of tools, which check code, docstrings and documentation files. To run all style checks use tox -e lint.

Releasing

Before releasing, make sure the version number is incremented and the release notes reference the new release. Running tests once more is also good practice. The following commands build source and wheel distributions to a clean directory, and publish them on PyPI according to the project name specified in the project metadata.

$ rm -r dist
$ python -m build
$ twine check --strict dist/*
$ twine upload dist/*

If you’d like to test the upload and the resulting package, use TestPyPI instead.

$ twine upload --repository testpypi dist/*
$ pip install --index-url https://test.pypi.org/simple/ mold