From 2baee5e2f59610722360771f5689a9c2ec4e297f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Schm=C3=B6lder?= Date: Thu, 13 Aug 2026 10:36:25 +0200 Subject: [PATCH 1/3] Docs: Add contributing guide --- CONTRIBUTING.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ee6d41d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,95 @@ +# Contributing to CADET-RDM + +This file covers the mechanics of working on CADET-RDM: development setup, tests, documentation, and releases. +For what the project is and where it is going, see [PROJECT.md](PROJECT.md). +For user-facing installation and usage, see https://cadet-rdm.readthedocs.io. + + +## Development setup + +Clone the repository and install it in editable mode together with the testing dependencies: + +```bash +git clone git@github.com:cadet/CADET-RDM.git +cd CADET-RDM +pip install -e . --group testing +``` + +The `--group` flag requires pip 25.1 or newer. +A dedicated conda or virtual environment is strongly recommended, since CADET-RDM inspects the active environment when recording run metadata. + +Two things outside the Python environment are required before the test suite will pass. + +Git LFS must be installed and initialized (`git lfs install`), because CADET-RDM tracks common data filetypes through LFS. +Installation instructions per platform are in the [user documentation](https://cadet-rdm.readthedocs.io/en/latest/user_guide/installation.html). + +Git needs a global identity, because the tests create repositories and commit to them: + +```bash +git config --global user.name "Your Name" +git config --global user.email "you@example.com" +``` + + +## Tests + +The suite lives in `tests/` and runs under pytest. +Tests create real Git repositories in temporary directories, so they are slower and more side-effect-heavy than pure unit tests. + +Four markers are defined in `pyproject.toml`: + +- `slow` for long-running tests, +- `server_api` for tests that talk to the GitLab or GitHub API, +- `container` for tests that require Docker, Podman, or Apptainer, +- unmarked tests, which need nothing beyond a local Git installation. + +CI runs only the unmarked subset: + +```bash +pytest tests -m "not server_api and not container and not slow" +``` + +Run that selection locally before opening a pull request. +The marked subsets require credentials or a container runtime and are expected to be run deliberately, not by default. + +Tests are executed on Ubuntu against Python 3.11, 3.12, and 3.13, plus one Windows and one macOS job on 3.13. +The minimum supported Python version is 3.11. + + +## Documentation + +The documentation source is Sphinx with MyST markdown under `docs/source`, published to Read the Docs. + +```bash +pip install -e . --group docs +cd docs +sphinx-build -b html source build +``` + +The rendered output is in `docs/build` and can be opened in any browser. +User-facing behavior changes should be reflected in `docs/source/user_guide` in the same pull request that changes the behavior. + + +## Branches and pull requests + +Work happens on feature branches that are opened as pull requests. +CI runs the test stage on pull requests against any branch, and on pushes to `main` and `dev`. + +Until its fate is settled, base new work on `main` and ask if in doubt. + +Commit subjects are short and imperative, optionally prefixed with the area of the change (`Docs:`, `Fix:`, `Feat:`, `Tests:`, `CI:`). +The subject says what changed; the body, where one is needed, says why. + + +## Releases + +Releases are published to PyPI from GitHub. + +1. Bump `__version__` in `cadetrdm/__init__.py`. + The package version is read from that attribute, so it is the single source of truth. +2. Update `.zenodo.json` if authorship or metadata changed. +3. Commit, tag as `vX.Y.Z`, and push the tag. +4. Publish a GitHub release for the tag. + +Publishing the release triggers `.github/workflows/release.yml`, which builds the distributions and uploads them to PyPI through trusted publishing. +The workflow deliberately triggers on published releases rather than on tags, to avoid running twice for a single release. From d5b26c6863f6379f23a9edc66f9d5f788f139c61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Schm=C3=B6lder?= Date: Thu, 13 Aug 2026 10:50:39 +0200 Subject: [PATCH 2/3] Docs: Consolidate README guidance --- README.md | 4 ++-- docs/README.md | 16 ---------------- docs/source/index.md | 2 +- 3 files changed, 3 insertions(+), 19 deletions(-) delete mode 100644 docs/README.md diff --git a/README.md b/README.md index a633035..921328d 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![CI](https://github.com/cadet/CADET-RDM/actions/workflows/CI.yml/badge.svg)](https://github.com/cadet/CADET-RDM/actions/workflows/CI.yml) [![Documentation](https://readthedocs.org/projects/cadet-rdm/badge/?version=latest)](https://cadet-rdm.readthedocs.io) [![License](https://img.shields.io/github/license/cadet/cadet-rdm)](LICENSE) -[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/) +[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/) CADET-RDM is a Research Data Management toolbox developed at Forschungszentrum Jülich. It supports computational research projects by tracking code, data, environments, and generated results in a reproducible and shareable way. @@ -89,4 +89,4 @@ It includes installation instructions, usage guides for the different interfaces ## Project information - **License:** see [LICENSE](LICENSE) -- **Authors and contributors:** see [AUTHORS](AUTHORS.md) \ No newline at end of file +- **Authors and contributors:** see [AUTHORS](AUTHORS.md) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 8681d57..0000000 --- a/docs/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# CADET-RDM Documentation - -To build the documentation locally, install sphinx and other dependencies by running - -``` -pip install -e .[docs] -``` -from the CADET-RDM root directory. - -Then, in the `docs` directory run: - -``` -sphinx-build -b html source build -``` - -The output is in the `build` directory and can be opened with any browser. diff --git a/docs/source/index.md b/docs/source/index.md index e5d9ae9..60de158 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,4 +1,4 @@ -```{include} ./user_guide/introduction.md +```{include} ../../README.md ``` ```{toctree} From 377a1f13eb7553dc68cd94fa7b9965829ccb0a27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Schm=C3=B6lder?= <20299934+schmoelder@users.noreply.github.com> Date: Thu, 13 Aug 2026 11:44:51 +0200 Subject: [PATCH 3/3] Add contributing section to README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 921328d..7486ec4 100644 --- a/README.md +++ b/README.md @@ -89,4 +89,5 @@ It includes installation instructions, usage guides for the different interfaces ## Project information - **License:** see [LICENSE](LICENSE) +- **Contributing:** see [CONTRIBUTING](CONTRIBUTING.md) - **Authors and contributors:** see [AUTHORS](AUTHORS.md)