Contributing

The project homepage is on GitHub.

Contributors and contributions are welcome via pull requests from a fork targeting the parent main branch.

A simple Git workflow, using a feature and/or fix branch created off the main branch of your fork, is recommended.

Cloning

If you wish to contribute please first ensure you have SSH access to GitHub. If you do then this should work:

ssh -vT git@github.com

If not please follow the SSH instructions linked above.

Once you’ve forked the repository, it is recommended to clone your fork over SSH:

git clone git+ssh://git@github.com/<fork user>/continuedfractions

Dependencies & PDM

As mentioned earlier, the package has no (production) dependencies, but groups of development requirements are specified in the [tool.pdm.dev-dependencies] section of the project TOML. Of these only the 'test' dependencies, including pytest and pytest-cov, are important.

test = [
    "coverage[toml]",
    "pytest",
    "pytest-cov",
    "pytest-xdist",
]

PDM is used (by myself, currently, the sole maintainer) to manage all dependencies and publish packages to PyPI. 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, which defines metadata for all TOML-defined development dependencies, including the currently empty set of production dependencies, and their sub-dependencies etc. This can be used to install all development dependencies, including the project itself, in editable mode where available:

pdm install -v --dev

Note

It is important to note that the pdm install uses either the default pdm.lock lockfile, 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.

Makefile and Tests

The Makefile defines three main targets: lint for Ruff linting, doctests for running doctests and unittests for running unittests and measuring coverage, using pytest and the pytest-cov plugin:

make lint
make doctests
make unittests

Linting warnings should be addressed first. The doctests serve as acceptance tests, and are best run after the unit tests.

Documentation

Project documentation is defined and built using Sphinx, and deployed to Read The Docs. Currently, the building and deployment steps for documentation are not automated in a CI pipeline, but are done manually - this will be addressed in future releases.

The Sphinx documentation can be built locally on any branch from the project root using:

make -C docs "html"

First, ensure that you have installed the docs Python requirements, which include all development dependencies, either via pip:

pip install -r docs/requirements.txt

or via PDM:

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

Continuous Integration and Deployment (CI/CD)

The CI/CD pipelines are defined in the CI YML, and pipelines for all branches include a tests stage, consisting of Ruff linting, Python doctests, and unit tests, in that order. This will be amended in the future to ensure that tests are only run on updates to PRs targeting main, to avoid duplication on main.

Versioning and Releases

The PyPI package is currently at version 0.11.33 - the goal is to use semantic versioning consistently for all future releases, but some earlier releases do not comply with strict semantic versioning.

There is currently no dedicated pipeline for releases - both GitHub releases and PyPI packages are published manually, but both have the same version tag.

Pipelines for releases (and also documentation) will be added as part of a future release.