Skip to content

Contributing

This project is a community effort and lives off your contributions. It follows the contributing guide of ELIXIR On-Cloud, which covers getting started, issues, branches and pull requests, commit messages and pull request titles, pull requests prepared with AI agents, the code of conduct and the security policy. This page covers what is specific to this repository, an app built with FOCA: see Development for how to set up a development environment.

Commit messages and pull request titles

Use feat, fix, perf, refactor and style only for changes of what is deployed: the app (trs_filer/) and its Helm chart (deployment/). The CI job PR title checks the titles of pull requests, which are the commit messages of squash merges.

Citation metadata

TRS-Filer is cited with the metadata in CITATION.cff (Citation File Format), which GitHub ("Cite this repository") and Zenodo use (see Citation). Its authors are the people who committed at least 100 lines (lines added) to main, the release branch (to dev before the first release), not counting merge commits, bots, vendored or generated files, the license text, binary files and the reformatting commits in .git-blame-ignore-revs. They are ordered by lines, then by commits; equal contributors are listed alphabetically by family name and marked with an asterisk (*). Affiliations come from public ORCID records only. To add or correct your entry (e.g., your name, ORCID iD or affiliation), open a pull request that changes only your entry; don't add e-mail addresses. CI validates the file (cffconvert --validate). Before each release, python scripts/citation.py set X.Y.Z sets its version and date-released, and the release workflow fails if they don't match the release (python scripts/citation.py check X.Y.Z; see Versioning and releases).

Python guidelines

The app targets one Python version, that of the base image in the Dockerfile (3.13): it is the minimum of requires-python in pyproject.toml, the target of ruff and mypy, and the version of CI and Read the Docs (tests/test_config.py and tests/test_docs.py check that they match). Most of the following is checked by pre-commit and CI (see Development for how to run the checks locally); the rest is checked in reviews.

  • Packaging: the package, its dependencies and the configuration of the tools are in pyproject.toml; runtime dependencies in project.dependencies, those for development and the documentation in the extras dev and docs. uv.lock locks them all, at exact versions and with hashes, and CI's checks run on the locked versions. After changing dependencies, run uv lock and commit uv.lock with the change (see Dependencies). Don't add setup.py or requirements files.
  • Formatting and linting: ruff formats the code (ruff format, compatible with Black, 88 characters per line) and lints it (ruff check) with the rule set shared by FOCA and FOCA apps: pycodestyle, Pyflakes, isort, flake8-bugbear, flake8-comprehensions, flake8-simplify, Pylint, Ruff's own rules, pyupgrade, bandit (security), logging format and pydocstyle, also for the tests (pyproject.toml, where each ignored rule says why). Prefer explicit checks to suppressions (# noqa, # type: ignore); justify the rare exceptions in the comment.
  • Docstrings: Google-style docstrings at all levels: packages, modules, classes, methods and functions, also private ones and tests, with a one-line summary and, where applicable, the sections Args, Returns (or Yields), Raises and, for classes, Attributes; consider Examples and Note. Ruff's pydocstyle rules (Google convention) check those of public objects and their Args; reviews check the others. The API reference is generated from them.
  • Type hints: complete type hints for all functions and methods (also of the tests), including *args and **kwargs, and generic types with their parameters (e.g., dict[str, Any], not dict); add hints to module-level variables and to local variables whose type isn't obvious. mypy checks the hints, and that functions and generic types have them (disallow_untyped_defs, disallow_any_generics); reviews check those of variables.
  • Tests: pytest, with coverage measured by coverage of trs_filer, scripts and docs/hooks.py, reported to Codecov by CI: cover all code that you add or change, with tests that fail without your change.
  • Further checks: ast-grep (rules in .ast-grep/, with tests), semgrep (security rules in .semgrep/), gitleaks (secrets) and actionlint (workflows), and pre-commit's checks of YAML, whitespace, merge conflicts and large files.

Suppress a finding only if it is a false positive or can't be avoided, on its line, with a comment with the reason (see Development).

Documentation

Update the documentation with every change that affects it: the pages in docs/ (built with MkDocs, see Documentation), the README of the Helm chart and the docstrings. Describe user-visible changes in the pull request, and how to upgrade existing deployments on the Upgrading page.