Developer Guide

Download Git sources

The official source code is hosted on GitHub: bootlin/sbom-cve-check

$ git clone https://github.com/bootlin/sbom-cve-check.git

Python virtual environment

The minimum supported version of Python is 3.10, as stated in the user guide.

We suggest creating a Python virtual environment to install the dependencies for development.

To create a Python virtual environment:

$ python3 -m venv .venv

Once it is created, you can activate it:

$ source .venv/bin/activate

pip version 25.1 or later is required to install development tool dependencies, if needed, update it:

(.venv) $ pip install --upgrade pip

Documentation Generation

The documentation source files are located in the docs directory. To build the documentation using Sphinx, follow these steps:

Create a Python virtual environment.
Install the documentation dependencies in your virtual environment:
```
(.venv) $ pip install --group docs
```
Build the HTML documentation from the docs directory:
```
(.venv) $ cd docs
(.venv) $ make html
```
The generated documentation will be available at docs/_build/html/index.html.

To build the documentation using uv (without manually creating a virtual environment), run the following command from the repository root:

$ uv run --group docs make -C docs html

The command below, executed from the docs directory, could be used to watch for any file changes under the docs directory and rebuild the documentation automatically:

while sleep 1 ; do make clean; find -name '*.md' | entr -d make html ; done

Tool Installation for Development

For standard tool usage, follow the installation instructions in the User Guide.

For development purposes, it is highly recommended to install the tool in editable mode with all optional dependencies:

(.venv) $ pip install -e .[extra]

Alternatively, you can install only the dependencies and use the src/sbom-cve-check executable directly.

Linter and Static Analysis

Create a Python virtual environment (if not already done).
Install the linter and static analysis tools:
```
(.venv) $ pip install --group lint
```

Install all optional dependencies:

(.venv) $ pip install -e .[extra]
(.venv) $ pip install --group test

Ruff

This project uses Ruff for linting and code formatting.

To run Ruff from an activated virtual environment:

Format the code:
```
(.venv) $ ruff format
```
Check the code:
```
(.venv) $ ruff check
```

Check and apply fixes (including unsafe fixes):

(.venv) $ ruff check --unsafe-fixes --fix

To run Ruff using uv (instead of manually creating a virtual environment), use for example:

$ uv run --group lint ruff check

mypy

This project uses mypy for static type checking.

To run mypy from an activated virtual environment:

Check the code:
```
(.venv) $ mypy .
```
Specify the Python version (if needed):
```
(.venv) $ mypy --python-version 3.14 .
```

To run mypy using uv (instead of manually creating a virtual environment):

$ uv run --group test --group lint --extra extra mypy .

ty

This project also uses ty for static type checking.

To run ty from an activated virtual environment:

(.venv) $ ty check --python-version 3.14 .

Note

Always specify the Python version in use.

To run ty using uv (instead of manually creating a virtual environment):

$ uv run --group test --group lint --extra extra ty check --python-version 3.14 .

pylint

This project does not enforce pylint rules, but it is recommended to run the following command to detect potential issues:

pylint -d "C0114,C0115,C0116,C0411,C0302,C0325" -d design src/

Tests

Create a Python virtual environment (if not already done).
Install the tool with all optional dependencies if this is not already the case:
```
(.venv) $ pip install -e .[extra]
```
Install the test dependencies:
```
(.venv) $ pip install --group test
```

To run the tests from the tests directory:

(.venv) $ pytest -v .

To run tests with coverage:

(.venv) $ pytest -v --run-slow --cov=sbom_cve_check --cov-config=../pyproject.toml .

To generate the associated HTML coverage report:

(.venv) $ coverage html

To run the tests using uv (instead of manually creating a virtual environment), from the repository root:

$ uv run --group test --extra extra pytest -v tests

For test troubleshooting:

Set the environment variable SBOM_CVE_CHECK_TEST_KEEP_TMP=1 to retain temporary directories after test execution (requires Python 3.12+). The temporary directory path is typically named: /tmp/sbom-cve-check-xxxxx.
For a very detailed test failure output, create a tests/pytest.ini file with the following content:
```
[pytest]
addopts = --capture=no -vvvvv --showlocals
```

Contributing

Before submitting a pull request, verify locally that all checks pass.

This section provides a quick summary of the commands to execute for checking the code or documentation. The examples below use uv for brevity and must be run from the repository root. For more details, refer to the associated sections.

If the documentation was modified:

$ uv run --group docs make -C docs html

If the code was modified, run the linter and static analysis tools:

$ uv run --group lint ruff format
$ uv run --group lint ruff check
$ uv run --group test --group lint --extra extra mypy --python-version 3.14 .
$ uv run --group test --group lint --extra extra ty check --python-version 3.14 .

If the code was modified, also run the tests:

$ uv run --group test --extra extra pytest -v tests

Pull Request Checklist

Ensure the following items are addressed before submitting your pull request:

Tests pass locally.
Linter and static analysis tools pass locally (no errors or warnings).
Commit messages follow the project convention (include a Signed-off-by: line in each commit message).
Tests added/updated (new functionality or bug fixes must include corresponding tests).
Documentation updated (if applicable, update relevant documentation).
Changelog updated (add an entry to the changelog for notable changes).

Release process

To prepare a new release, follow these steps:

Update the Changelog
- Add relevant changes to CHANGELOG.md.
- Remove the (Unreleased) suffix from the latest version entry.
Update the Version
- In src/sbom_cve_check/__init__.py, remove the .dev0 suffix from the current version.
Create a Git Tag
- Create an annotated Git tag using the format v1.X.Y.
Push Changes
- Push both the main branch and the tag to the remote repository.
Publish Release
- Run the GitHub workflow publish-release from the Actions tab.
- Select the tag to publish from Use workflow from (do not select a branch).
- This workflow is going to automate the following (manual) steps:
  - Ensure the test GitHub action is executed and verify that all checks pass.
  - Create a GitHub release from the pushed tag. For the release description follow this example.
  - Generate the distribution archives using:
    python3 -m build
  - Upload the archives to PyPI using:
    python3 -m twine upload dist/*
    For more details see the documentation.
Verify Documentation Tagging
- Ensure the documentation on Read the Docs has been automatically tagged for the created release: The tagged version should appear in the drop-down menu in the left panel.
Prepare for Next Development Cycle
- Increment the version in src/sbom_cve_check/__init__.py and append the .devZ suffix, with Z the patch part of the previous release. For example:
  - If previous release is v1.3.0, set current version to v1.4.0.dev0.
  - If previous release is v1.3.1, set current version to v1.4.0.dev1.
- Add the next version entry to CHANGELOG.md with the (Unreleased) suffix.

Roadmap & planned developments

The following features are intended to be developed in the medium term:

Add support of Ubuntu CVE tracker repository
- Automatically detect if a patch was backported
Add CycloneDX (CDX) SBOM support as input.
Add more export formats, like, for example, OpenVEX.

The following features are intended to be developed in the very long term:

Allow to generate an SBOM (CDX or SPDX 3.0) as output even if the SBOM specified as input is in another format.