Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
172 lines (121 loc) · 5.09 KB

CONTRIBUTING.md

File metadata and controls

172 lines (121 loc) · 5.09 KB

Contributing to Testflinger

This document provides the information needed to contribute to Testflinger, its providers, and its documentation.

Repository structure

Testflinger is a monorepo with a subproject directory for each of the major components of Testflinger, such as agent, cli, common, device-connectors, and server.

Package and Project Management

Each of the subprojects uses uv as the package and project manager. You can install uv with snap:

sudo snap install --classic astral-uv

Development Environment

Within a subproject, you can set up the virtual environment with the following command:

uv sync

Then you can activate the virtual environment:

source .venv/bin/activate

To learn more about uv, refer to the uv documentation.

Managing Dependencies

Add a Dependency

To add a new dependency to a subproject, please use uv, as it will automatically add it to both the pyproject.toml and uv.lock files:

uv add ...

If the dependency is only a development dependency, please add it to the dev dependency group by using the --dev flag.

To learn more about the uv add command, refer to the uv documentation.

Remove a Dependency

To remove a dependency from a subproject, please use uv, as it will automatically remove it from both the pyproject.toml and uv.lock files:

uv remove ...

If the dependency is only a development dependency, please remove it from the dev dependency group by using the --dev flag.

To learn more about the uv remove command, refer to the uv documentation.

Update Lock File

If there is a discrepancy between a subproject's pyproject.toml and lock file, you can generate the lock file (uv.lock) with:

uv lock

To learn more about the uv lock command, refer to the uv documentation.

Testing

All of the linters, format checkers, and unit tests can be run automatically. Before pushing anything, it's a good idea to run tox from the root of the subproject where you made changes.

To run tox with uv, use:

uvx --with tox-uv tox

If you have tox installed, you can also just run tox from the subproject.

In case of any linting or formatting errors, all solvable fixes can be applied with:

uvx --with tox-uv tox run -e format

Server API Changes

If you modified the server API (endpoints, schemas, or parameters), you must update and commit the OpenAPI specification file (server/schemas/openapi.json) in the same pull request. The CI check will fail if the spec is out of sync.

To check if the specification is up-to-date, run:

uvx --with tox-uv tox run -e check-schema

If the check fails, regenerate the spec from the server/ directory:

uvx --with tox-uv tox run -e schema

Commit the updated spec file with your API changes.

Signed Commits

  • To get your changes accepted, please sign your commits. This practice is enforced by many of the CI pipelines executed in the repository (pipelines which use Canonical's github-runner-operator operated runners).

  • If you have just discovered the requirement for signed commits after already creating a feature branch with unsigned commits, you can issue git rebase --exec 'git commit --amend --no-edit -n -S' -i main to sign them. To translate this into English:

    • git rebase --exec: rebases commits
    • --exec '...': exec command '...' after each commit, creating a new commit
    • git commit --amend --no-edit: amend a commit without changing its message
      • -n: bypass pre-commit and commit-msg hooks
      • -S: GPG sign commit
      • -i: let the user see and edit the list of commits to rebase
      • main: to all the commits until you reach main

  • To make commit signing convenient (see this relevant Stack Overflow post), do the following:

    git config --global user.signingkey <your-key-id>
git config --global commit.gpgSign true
git config --global tag.gpgSign true
git config --global push.gpgSign if-asked

Pull Requests

Pull Requests will be marked as stale after 60 days of inactivity and closed after another 7 days of inactivity.

Issues

Issues will be marked as stale after a year of inactivity and closed after another 7 days of inactivity.

Documentation

Testflinger documentation is maintained under the docs/ subdirectory. To submit changes to the documentation, please read the documentation contributing guide.