CONTRIBUTING.md

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 [email protected]

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>/fsrapiclient

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 only depends on the requests library.

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 an auto-generated requirements.txt using:

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

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

Tests

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 ~fsrapiclient.api.FsrApiClient class:

python -m pytest -sv tests/units/test_api.py::TestFsrApiClient

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 fsrapiclient.api:

python -m doctest -v src/fsrapiclient/api.py

Documentation

This documentation site is written, built and deployed using reStructuredText, Sphinx, and Read the Docs (RTD) respectively. The Sphinx theme used is Furo.

CI

The CI pipelines are defined in the CI YML and the CodeQL Analysis YML. 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.4.0.

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

A separate release pipeline may be added as part of a future release.