Skip to content

Contributing

The general rules for contributing to proTES (getting started, issues, branches and pull requests, commit messages and pull request titles with their types, pull requests prepared with AI agents) are in the contributing guide of ELIXIR On-Cloud. This page covers what is specific to this repository, an app built with FOCA.

Commit messages and pull request titles

CI checks the title of a pull request (job PR title) and rechecks it when you edit it.

Use feat, fix, perf, refactor and style only for changes of what is deployed: the app (pro_tes/) and its Helm chart (deployment/).

Citation metadata

proTES is cited with the metadata in CITATION.cff (Citation File Format), which GitHub ("Cite this repository") and Zenodo use. Its doi is the Zenodo concept DOI, which stays the same for all versions (see Citation). Its authors follow the citation metadata rule of the contributing guide (not counting vendored files and the reformatting commits in .git-blame-ignore-revs). 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_build.py checks 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: keep it at 100% of pro_tes and scripts, which is enforced: coverage report (and CI) fails below 100% (fail_under in pyproject.toml), and so do Codecov's checks of the whole code and of the changes of a pull request (codecov.yml). Add 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 in the notes of the next release if they exist already (docs/releases/, see Versioning and releases).