Skip to content

Latest commit

 

History

History
95 lines (58 loc) · 4.5 KB

CONTRIBUTING.md

File metadata and controls

95 lines (58 loc) · 4.5 KB

google-site-verification
3F2Jbz15v4TUv5j0vDJAA-mSyHmYIJq0okBoro3-WMY

Contributing

Contributors and contributions are welcome. Please read these guidelines first.

Git github

The project homepage is on GitHub.

Contributors can open pull requests from a fork targeting the parent mainbranch. But it may be a good first step to create an issue or open a discussion topic.

Repo folder

You will need to clone the repository first. As there are no dependencies there isn't much to set up, so this should be pretty simple. The minimum recommended version of Python is 3.10 as some of the type hinting may be incompatible with earlier versions.

Dependencies cubes

Only standard libraries are used. See the project TOML for more information.

Development dependencies are specified in the [tool.pdm.dev-dependencies] section of the TOML but these are purely indicative.

PDM is used to manage all dependencies. It is also used to automate certain tasks, such as running tests, as described in the section.

There are no root-level requirements*.txt files - but only a single (default, version-controlled, cross-platform) pdm.lock lockfile. The lockfile is used with PDM to install all development dependencies, including the project itself, in editable mode where available:

pdm install -v --dev

Note

The pdm install command uses either the default lockfile (pdm.lock), or one specified with -L <lockfile>. Multiple lockfiles can be generated and maintained. Refer to the PDM install documentation for more information.

If you don't wish to install any editable dependencies, including the project itself, you can use:

pdm install -v --dev --no-editable --no-self

The default lockfile can be updated with any and all upstream changes in the TOML-defined dependencies, but excluding any editable dependencies including the project itself, using:

pdm update -v --dev --no-editable --no-self --update-all

This will usually modify pdm.lock, in which case the file should be staged and included in a commit.

The lockfile can be exported in its entirety to another format, such as docs/requirements.txt using:

pdm export -v -f requirements --dev -o docs/requirements.txt

For more information on PDM lockfiles and installing requirements see the PDM documentation.

Tests microscope

Tests are defined in the tests folder and can be run directly or via the Makefile, e.g. make unitests will run the unit tests. Linting can be performed with make lint, which requires ruff (specified in the dev. dependencies in the TOML). The doctests can be run with make doctests.

Documentation book

Project documentation is written and built using Sphinx, and deployed to Read The Docs.

The Sphinx documentation source pages and assets are contained in the docs/ subfolder. The HTML pages can be built locally on any branch (from the project root) using:

make -C docs html

The pages will be built inside docs/_build/html, with the index/home page being docs/_build/html/index.html.

In order for this to work first ensure that you have installed the documentation Python requirements listed in docs/requirements.txt. This can be done either via pip:

pip install -r docs/requirements.txt

or via PDM:

pdm install -v --dev --no-editable --no-self

CI circle-play

The main CI workflow is CI YML, and there is also a static CodeQL Analysis YML.

Versioning and Releases upload

The latest release is 1.11.1, and releases are created, tagged and published manually, not via a workflow.