Contributing

Contributing#

Your contribution is warmly welcomed. You can help by:

  1. Spreading the word about this project, using our website sec-certs.org

  2. Trying the tool and reporting issues and suggestions for improvement (open a GitHub issue)

  3. Adding new regular expressions to extract relevant information from certificates (update rules.yaml)

  4. Performing additional analysis with extracted data (let us know about your findings)

  5. Improving the code (Follow Github contribution guidelines, ideally contact us first about your plan)

Dependencies#

For complete list of system dependencies, see docs/installation.

Requirements#

Requirements are maintained via uv. The main ideas are:

  • List actual dependencies in pyproject.toml without (unnecessarily) pinning them.

  • Use uv lock to resolve and lock the dependencies.

  • Use uv sync --inexact to install these dependencies. Use --inexact to keep the en_core_web_sm model installed by spacy.

  • Tests, linting and Docker all run against this reproducible environment of pinned requirements.

Branches#

main is the default branch against which all pull requests are to be made. This branch is not neccessarily stable, only the releases are. page is the branch in which the website https://sec-certs.org is developed.

Releases and version strings#

  • Version string is not indexed in git but can be retreived maintained by setuptools-scm from git tags instead.

  • setuptools-scm will automatically, upon editable/real install of a package, infer its version and write it to sec_certs/_version.py. This file is not indexed as well. See more at setuptools-scm GitHub

  • On publishing a release, the tool is automatically published to PyPi and DockerHub.

Note on single-sourcing the package version: More can be read here. The downside of our approach is that .git folder and editable/real installation is needed to infer the version of the package. Releases can be inferred without installing the project.

Currently, the release process is as follows#

  1. Update pre-commit dependencies with pre-commit autoupdate, pin new versions of linters into the dev depdendency-group of pyproject.toml.

  2. Run uv lock to update dependencies, commit the changes to uv.lock.

  3. Test the build by running uv build.

  4. Create a release from GitHub UI. Include release notes, add proper version tag and publish the release (or create it from scratch with new tag).

  5. This will automatically update PyPi and DockerHub packages.

Virtual environment#

We recommend using uv for managing your environment. The commands in this guide assume you are using it. If you do not want to prepend every command with uv run, you can use uv to setup a virtual environment for you and activate it:

uv venv
uv sync --dev --inexact
source .venv/bin/activate  # or {.fish,.nu,.bat,.ps1} depending on your shell

Quality assurance#

All commits shall pass the lint pipeline of the following tools:

These tools can be installed via uv sync --dev --inexact (alternatively this can be done via pip install -e . --group dev). You can use the pre-commit tool to register git hook that will evaluate these checks prior to any commit and abort the commit for you. Note that the pre-commit is not meant to automatically fix the issues, just warn you.

It should thus suffice to:

uv sync --dev --inexact
uv run pre-commit install
uv run pre-commit run --all-files

To invoke the tools manually, you can, in the repository root, use:

  • Mypy: uv run mypy .

  • Ruff: uv run ruff . (or with --fix flag to apply fixes)

  • Ruff format: uv run ruff format --check .

Tests#

Tests are run with pytest. The tests are located in tests folder and are run with uv run pytest tests. The tests are also run on every push to the repository with Github Actions. There are two custom markers for the tests:

  • slow for tests that take longer time to run

  • remote for tests that require remote resources and are thus flaky.

To exclude slow tests, use uv run pytest -m "not slow". To exclude remote tests, use uv run pytest -m "not remote". To run only slow tests, use uv run pytest -m "slow". To run only remote tests, use uv run pytest -m "remote".

Documentation#

Every public method of a module that can be leveraged as an API by user should be documented. The docstring style should be sphinx.

The documentation is built using sphinx with mnyst extension that allows for markdown files. Folder notebooks/examples is symbolically linked to /docs and its contents will be automatically parsed. These notebooks are supposed to be runnable from Binder.

Contents