Contributing

Welcome to Festo CycloneDX Editor Validator contributing guide, thank you for investing your time in contributing to our project! To get an overview of the project, read the documentation.

Issues

Create Issues

Before submitting, please ensure that you are using the latests code by performing a git pull, respectively pip install -upgrade cyclonedx-editor-validator. Also, please ensure that an issue does not already exists.

Always include your python version number (python --version) and the tool version (cdx-ev --version).

Solve Issue

Feel free to assign issues to yourself and make changes to our tool. Please consider the points mentioned here.

Make changes to CycloneDX Editor Validator

Prerequisites

For compatibility reasons, the code should be compliant to python 3.10 or higher.
Make sure to use the latest code by performing a git pull.
For a major change it is recommended that you get in touch with us by creating an issue to discuss changes prior to dedicating time and resources. This process allows us to better coordinate our efforts and prevent duplication of work.
Commit your changes using a descriptive commit message that follows our commit message format. The same applies for titles of PRs. This is required as we generate our release notes from these messages.
Otherwise, feel free to directly submit a pull request.

Write new commands, options or arguments

Please consider the following rules for commands, options and arguments:

Argument type	Style	Examples
Subcommand	kebab-case [1]	cdx-ev init-sbom
Option	kebab-case	cdx-ev --issues-file
Option value	<kebab-case> [1]	cdx-ev --issues-file <file>
Positional argument	<snake_case>	cdx-ev merge <sbom_file>
Optional position argument	[<kebab-case>]	No good examples, yet.

Footnotes:

Submitting Pull Requests

The following things are to consider before submitting a pull request.

All tests should be passing.
If you provide a new feature also include tests for it.
Please ensure that types are correct according to mypy.
All submitted code should conform to PEP8 and ruff.
The code should be python 3.10 compliant.

Commit Message Format

The message format was mainly inspired by the guidelines of Angular.

Please use the following format:

<type>: <subject>

<optional footer with additional details>

Type

Must be one of the following:

feat: A new feature
fix: A bug fix
docs: Documentation only changes
refactor: A code change that neither fixes a bug nor adds a feature. (e.g., style or performance changes)
tests: Adding missing or correcting existing tests
chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Subject

The subject contains succinct description of the change:

Use the imperative, present tense: “change” not “changed” nor “changes”
Don’t capitalize first letter
No dot (.) at the end
Do not describe the reason of the change, describe the content of the change (what, not why).

Examples

fix: do not add license option to default operations

feat: add 'amend' option

refactor: apply ruff

Setting up the Development Environment

Before you begin, ensure the following are installed:

Git (for version control)
Optional: Python 3.10+ (if you plan using pip to install uv, otherwise uv will handle Python installations for you)

Installing uv

If uv is not yet installed on your system:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | less

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | more"

# Alternatively, via pip (not recommended)
pip install uv

This provides uv, which automatically handles Python versions, environment creation, dependency resolution, and isolated environments.

From now on: Do not run Python / pip directly. All Python commands must be run via `uv`.

Environment Variables for Corporate Usage

Development in corporate contexts may require special environment variables, such as:

PRE_COMMIT_HOME: Specifies the directory for caching pre-commit related files.
UV_PYTHON_INSTALL_DIR: Specifies the directory for storing managed Python installations.
UV_PYTHON_BIN_DIR: Specifies the directory to place links to installed, managed Python executables.
UV_PYTHON_CACHE_DIR: Specifies the directory for caching the archives of managed Python installations before installation.
UV_CACHE_DIR: Specifies the directory for caching instead of the default cache directory.
UV_TOOL_BIN_DIR: Specifies the “bin” directory for installing tool executables.
UV_TOOL_DIR: Specifies the directory where uv stores managed tools.

Example export (assuming git bash):

export PRE_COMMIT_HOME=C:/opt/corp/pre-commit
export UV_PYTHON_INSTALL_DIR=C:/corp/uv
export UV_PYTHON_BIN_DIR=C:/corp/uv/bin
export UV_PYTHON_CACHE_DIR=C:/corp/uv/cache
export UV_CACHE_DIR=C:/corp/uv/cache
export UV_TOOL_BIN_DIR=C:/corp/uv/tools/bin
export UV_TOOL_DIR=C:/corp/uv/tools

You can also maintain a .bashrc file that is sourced by your shell as needed.

Setting Up the Environment

For the creation of the development environment, run the following command:

# Using uv to install the correct Python version
uv python install 3.10

Once inside your project directory:

# Sync and install all declared dependencies (runtime + dev)
uv sync

This creates and populates the local environment based on pyproject.toml and uv.lock.

If you want to add dependencies, e.g. for development, use:

uv add --group dev <package-name>

We enforce pre-commit to run checks (linters, formatters, etc.) prior to each commit. It should be installed inside the `uv` environment and registered for the repository.

Install pre-commit with uv:
```
uv tool install pre-commit
```
Register hooks:
```
uv run pre-commit install
```
You can also run all pre-commit checks manually:
```
uv run pre-commit run --all-files
```

Typical Workflow and Contribution

Clone the repository:

git clone https://github.com/Festo-se/cyclonedx-editor-validator.git

Develop features / fix bugs.
Add tests if necessary.
Validate changes locally (tests, linting, formatting).

uv run coverage run -m pytest
uv run ruff check cdxev tests --fix
uv run mypy --install-types --non-interactive --config-file=pyproject.toml
uv run pre-commit run --all-files

Commit changes (pre-commit auto-runs).
Push and open a pull request.