# Developer Guide

## Download Git sources

The official source code is hosted on GitHub:
[bootlin/sbom-cve-check](https://github.com/bootlin/sbom-cve-check)

```sh
$ 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](user-guide.md#dependencies--installation).

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

- To create a Python virtual environment:
```sh
$ python3 -m venv .venv
```
 - Once it is created, you can activate it:
```sh
$ source .venv/bin/activate
```
 - pip version 25.1 or later is required to install development tool
   dependencies, if needed, update it:
```sh
(.venv) $ pip install --upgrade pip
```

## Documentation generation

The documentation sources are in `docs`. To build them using Sphinx, run
the following commands:

 - First create a [Python virtual environment](#python-virtual-environment)
   and update pip.
 - Install the dependencies to generate this documentation in your Python
   virtual env:
```sh
(.venv) $ cd sbom-cve-check
(.venv) $ pip install --group docs
```
 - You can now build the docs in HTML, from the `docs` directory:
```sh
(.venv) $ cd sbom-cve-check/docs
(.venv) $ make html
```
 - The generated documentation will be available under
   `docs/_build/html/index.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:

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

## Tool installation for development

For normal use of the tool, it should be installed as described in the
[user guide](user-guide.md#dependencies--installation).

As an alternative, only the dependencies could be installed, and we could use
the `src/sbom-cve-check` executable. But for development purposes, it is
instead highly recommended to "install" the tool using the `--editable` flag:
```sh
(.venv) $ pip install -e .
```

For development purposes, to "install" it with all optional dependencies, run:
```sh
(.venv) $ pip install -e .[extra]
```

## Linter and static analysis

First create a [Python virtual environment](#python-virtual-environment),
if not already done, and update *pip*.

Then, to install the tools, run:
```sh
(.venv) $ pip install --group lint
```

It may be necessary to install the various dependencies, for example using:
```sh
(.venv) $ pip install -e .[extra]
(.venv) $ pip install --group test
```

### Ruff

This project uses the [Ruff](https://docs.astral.sh/ruff/) linter.

### mypy

This project uses [mypy](https://mypy.readthedocs.io/en/stable/) for static
type checking.

## pylint

This project does not enforce [pylint](https://pylint.readthedocs.io/en/stable/)
rules. The use of this static analysis tool is optional. But it is recommended
to run the following command to search for new warnings:

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

## Tests

First create a [Python virtual environment](#python-virtual-environment),
if not already done, and update *pip*.

Then, install the tool with all optional dependencies if this is not already
the case. For example run:
```sh
(.venv) $ pip install -e .[extra]
```

Then, to install the test tools, run:
```sh
(.venv) $ pip install --group test
```

To execute the test, run the following command from the `tests` directory:
```sh
pytest -v .
```

To execute the test with the coverage, run the following command from the
`tests` directory:
```sh
pytest -v --run-slow --cov=sbom_cve_check --cov-config=../pyproject.toml .
```
Then, to generate the HTML report, execute:
```sh
coverage html
```

For test troubleshooting, is it possible to define the
`SBOM_CVE_CHECK_TEST_KEEP_TMP` environment variable to `1`. The temporary
directories generated during the tests will not be deleted. Note: to use this
environment variable, at least Python 3.12 is required.

## 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 branch and the tag to the remote repository.
- **Run GitHub Actions**
   - Ensure the GitHub action is executed (if not already done) and verify that
     all checks pass.
- **Create a GitHub Release**
   - Create a GitHub release from the pushed tag.
   - For the release description follow this [example](
     https://github.com/bootlin/sbom-cve-check/releases/tag/v1.1.0).
- **Upload to PyPI**
   - Generate the distribution archives using:
     ```bash
     python3 -m build
     ```
   - Upload the archives to PyPI using:
     ```bash
     python3 -m twine upload dist/*
     ```
   For more details see the [documentation](
   https://packaging.python.org/en/latest/tutorials/packaging-projects).
- **Verify Documentation Tagging**
   - Ensure the documentation on [Read the Docs](
     https://sbom-cve-check.readthedocs.io/) 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
     `.dev0` suffix.
   - 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.