CONTRIBUTING.md

google-site-verification
3F2Jbz15v4TUv5j0vDJAA-mSyHmYIJq0okBoro3-WMY

Contributing

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

Git

The project homepage is on GitHub.

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

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

Repo

If you wish to contribute please first ensure you have SSH access to GitHub. This basically involves creating a project-specific SSH keypair - if you don't already have one - and adding it to GitHub. If you have done this successfully then this verification step should work:

ssh -vT git@github.com

Some SSH configuration may be required: on MacOS or Linux your user-defined SSH configuration file (~/.ssh/config) should look something like this:

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  ForwardAgent yes
  Preferredauthentications publickey
  IdentityFile ~/.ssh/<SSH private key filename>
  PasswordAuthentication no

For Windows please consult the Windows OpenSSH documentation.

Once you’ve forked the repository, you can clone your fork, e.g. over SSH:

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

You can create additional remotes for the parent project to enable easier syncing, or you can simply create PRs directly against the parent project.

Dependencies & PDM

The package has no external (production) dependencies - some development dependencies are specified in the [tool.pdm.dev-dependencies] section of the project TOML, but they are not mandatory. Of these, the most important are probably the 'test' dependencies, including pytest and pytest-cov:

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 pdm install 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 should be run with pytest.

For convenience different types of test targets are defined in the Makefile: 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 unittests
make doctests

Linting warnings should be addressed first, and any changes staged and committed.

Unit tests can be run all at once using make unittests or individually using pytest, e.g. running the test class for the ~continuedfractions.lib.continued_fraction_rational function:

python -m pytest -sv tests/units/test_lib.py::TestContinuedFractionRational

Note

The -s option in the pytest command is to allow interactive environments to be entered on errors, e.g. debugger breakpoints. The default behaviour of capturing console input/output would otherwise prevent debuggers from being triggered.

The doctests serve as acceptance tests, and are best run after the unit tests. They can be run all at once using make doctests, or individually by library using python -m doctest, e.g. running all the doctests in ~continuedfractions.sequences:

python -m doctest -v src/continuedfractions/sequences.py

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 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/html, with the index/home page being docs/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/CD

The CI/CD pipelines are defined in the CI YML and the CodeQL Analysis YML, and, currently, pipelines for all branches include a tests stage that includes Ruff linting, unit tests, Python doctests, and in that order.

Versioning and Releases

The PyPI package is currently at version 0.17.4 - 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 will be added as part of a future release.