Contribute to This Plugin¶
Structure of this repository
The software is located inside src/nomad_eosc_galaxy_actions, with unit tests in tests,
standalone scripts (not part of the installed package) in scripts,
and the Galaxy-team-facing demo in examples/galaxy_demo.
Branching model¶
This plugin follows the same branching model as the core NOMAD packages.
| Branch | Role |
|---|---|
develop |
Default branch. All regular development PRs target this branch. |
main |
Released versions only. Only release/* branches are merged here, so its history is the release history. |
release/vX.Y.Z |
Temporary release branch, created from develop and merged into main. The version may carry a pre-release suffix, e.g. release/vX.Y.Z-beta or release/vX.Y.Z-rc1. |
| Activity | Branch |
|---|---|
| Feature development | develop |
| PR review and integration | develop |
| Selecting changes for a release | release/vX.Y.Z |
| Release-specific bug fixes | release/vX.Y.Z |
| Published release history | main |
| Porting release fixes back to ongoing development | Merge release/vX.Y.Z back into develop |
The Check if source is release/* workflow
(.github/workflows/check-source-is-release.yml)
allows PRs into main only from release/* branches. PRs from any other branch, including develop,
fail this check. It is enforced by marking it as a required status check in the branch protection rule
for main.
Setup¶
Requires Python 3.10+. We recommend uv, an extremely fast Python package and project manager; a more classical venv/pip
approach works too.
Development installation¶
git clone https://github.com/FAIRmat-NFDI/nomad-eosc-galaxy-actions.git \
--branch develop
cd nomad-eosc-galaxy-actions
Install the package in editable mode, together with its dev dependencies:
Linting, formatting, and pre-commit hooks¶
We use Ruff for linting/formatting and mypy for type checking, run via pre-commit:
pre-commit install # installs the git hook, once per clone
pre-commit run --all-files # run all hooks against the whole repo once
You can also run Ruff directly:
In the pre-commit as well as in the GitHub CI, we use cspell for spellchecking. If cspell flags a real (correctly spelled) word, add it to .cspell/custom-dictionary.txt through this script:
Testing¶
Unit tests are written with pytest:
The Galaxy round trip itself isn't exercised by the unit test suite — it needs a real Galaxy account. scripts/test_galaxy_roundtrip.py covers that separately; see the tutorial.
Contributing on GitHub¶
Commit your changes on a separate branch created from develop and open a pull request against develop:
git switch develop && git pull
git switch -c <short-descriptive-name>
# commit your changes, then
git push -u origin <short-descriptive-name>
Never open a pull request against main: it receives only release/* branches. CI checks linting, runs the tests, and builds the docs; once those pass and a review happens, the PR can be merged.
Changing something in docs/? See How-to guides > Contribute to the Documentation for the writing conventions, how to build the docs locally, and how to add a new page.
Release workflow¶
-
Create the release branch from
develop: -
Commit only release-specific changes on this branch (version bumps, changelog, last-minute bug fixes). New features keep going into
develop. - Bump
versioninCITATION.cfftoX.Y.Z, including any pre-release suffix (e.g.0.1.2-rc1for the tagv0.1.2-rc1). The package version itself comes from the git tag;publish.yml'scff-version-checkjob fails ifCITATION.cffdiffers from it. - Open a PR from
release/vX.Y.Zintomain. Do not merge yet! - Create a GitHub release with the tag
vX.Y.Zand selectrelease/vX.Y.Zas its target branch. The publish workflow refuses to upload to PyPI if the release does not targetrelease/vX.Y.Zor if the tagged commit is not on that branch. - Once CI passes and the release is published to PyPI, merge the PR.
- If you fixed anything directly on the release branch, open a PR from
release/vX.Y.Zintodevelopso the fixes are not lost in ongoing development. - Delete the
release/vX.Y.Zbranch.
Developing this plugin as part of NOMAD¶
If you're working on this plugin's NOMAD integration (the Action, the trigger entry schema) rather than just galaxy_client.py in isolation, use nomad-distro-dev, FAIRmat's development environment for NOMAD and its plugins. See How-to guides > Install this Plugin for how this repo is
wired into that workspace.
Troubleshooting¶
If you hit an issue with the plugin or with setting up the development environment, open a GitHub issue.