Skip to content

Contributing Guidelines

This guide explains how to set up a development environment, how to make various changes, including documentation and deployments. It also explains the relevant workflows for various development tasks.

Environment Setup

  1. Create a Python virtual environment

    Typically, this requires:

    python3 -m venv venv
source venv/bin/activate

    For additional details and troubleshooting, see Python documentation on virtual environments.

  2. Install required development dependencies

    python -m pip install -r requirements-dev.txt

Source Code Changes

Debugging Changes

The source code is in pymwp directory. When running from source, use the command:

python3 -m pymwp [args]

Checking Changes

Any changes to source code must pass lint and unit tests. These are checked automatically for PRs and commits to main branch. 

make pre-commit   # check everything
make test         # check unit tests only
make lint         # check code style only

  • This project uses flake8 for linting. You can use it to check specific files, or run against all Python source files, by specifying a path.

  • Unit tests are in tests directory. You can run unit tests on specific files or the entire source. See pytest documentation for more details.

  • There are additional interesting performance checks, e.g., benchmarking and profiling. These are documented in utilities.

Relevant workflows

Build checks code changes using the latest Python runtime.

Version test checks code changes against various Python runtimes.

Documentation

Setting up the code environment and dependencies, also includes the setup for pymwp docs. The documentation is built with mkdocs.

If you want to build and run the documentation website locally, run:

python -m pip install -r requirements-doc.txt
mkdocs serve

This will launch a web server, by default at port 8000 (https://localhost:8000). Then it is possible to preview documentation changes locally in browser.

Once those changes are satisfactory, commits to main branch will automatically deploy the documentation changes.

Relevant workflows

Docs builds and pushes documentation to gh-pages branch.

pages-build-deployment deploys gh-pages branch.

Code Releases

Tagging a commit in main branch will automatically kick off a deployment and release,
for all configured distribution channels.

Python Package Index

  • Builds and uploads a distribution version of the software.
  • The meta data for PyPI release is defined in setup.py

GitHub Release

  • Creates a release with relevant release assets.
  • These assets are defined in the publish-workflow.
  • Release details can be edited manually and after release.

Zenodo archival deposit

  • Following GH release event, Zenodo webhook will generate a comparable archival release.
  • Pre-set meta data for Zenodo deposit is defined in .zenodo.json.
  • See deposit meta data docs for possible options.

Relevant workflows

Publish handles all release and deployment tasks.