Contributing and developing

Reporting issues

Report issues on the Cabby issue tracker.

Obtaining the source code

Download or clone the Cabby repository.

Layout

The Cabby repository has the following layout:

  • docs/ contains the documentation.
  • cabby/ contains the library and command-line tools.
  • tests/ contains the test suite.

Develop with uv

Install uv as described in the installation guide. From the repository root, create a virtual environment and install Cabby in editable mode with its development dependencies:

uv venv --python 3.12
uv pip install -r requirements-dev.txt -e .

Activate the environment before running the tests or CLI commands. In a POSIX shell, run . .venv/bin/activate. In PowerShell, run .\.venv\Scripts\Activate.ps1.

Running the tests

From the activated environment, run:

python -m pytest --cov=cabby
python -m flake8
taxii-discovery --help

To run the existing tox environments, use uvx --python 3.12 --with tox-uv tox -e py312,flake8.

To test a change to MISP/libtaxii together with Cabby, check out that repository as ../libtaxii. From a fresh Cabby virtual environment, install both checkouts in the same operation and run the client tests.

uv pip install -r requirements-dev.txt -e ../libtaxii -e .
python -m pytest tests/test_client10.py tests/test_client11.py tests/test_client21.py

Generating the documentation

The site uses the MISP book template. Install Quarto 1.9.38, uv, and Make. Then run the following from the repository root. The docs extra provides autodoc, which generates the API chapter from Cabby’s Python docstrings.

uv run --python 3.12 --extra docs make -C docs html

Open docs/_book/index.html to browse the result, or use uv run --python 3.12 --extra docs make -C docs preview while editing.

The Documentation workflow checks the site on pull requests and publishes it to GitHub Pages on pushes to master. For the initial setup, select GitHub Actions as the publishing source under Settings → Pages → Build and deployment. To redeploy, run the workflow manually from master.

Publish a release to PyPI

Before the first release, a PyPI maintainer must register a GitHub pending publisher on the PyPI publishing page. If the project already exists, use its Publishing settings. Enter these values so PyPI can identify the release job.

PyPI field Value
PyPI project name misp-cabby
Owner MISP
Repository name cabby
Workflow filename publish.yml
Environment name pypi
  1. Set the new version in cabby/_version.py, update CHANGES.md, and merge those changes into master.
  2. Publish a GitHub Release for that commit. Use the package version as the tag, for example 0.1.24.
  3. Check the Publish to PyPI workflow. It builds and validates the wheel and source distribution, checks the tag against the built version, and uses the pypi environment to obtain a short-lived publishing token. Both files appear on the misp-cabby project page.

Next steps

Continue to License.