Release Guide

This guide describes the complete, ordered sequence for cutting an nf-bids release: from version-bump through publication. Each step states the evidence it provides and the failure that blocks proceeding.

Complete all layers of the Testing Guide before starting a release.

Overview

The release sequence is:

  1. Version Bump

  2. Changelog Update

  3. Test and Validation Pass

  4. Documentation Build Pass

  5. Git Tag

  6. Plugin Publication

  7. Documentation Publication (Automated)

Step 1 — Version Bump

Two files must be updated atomically (in the same commit) to keep the plugin artifact version and the documentation site version in sync.

build.gradle

Locate the version declaration at the top of build.gradle:

version = '0.3.0'   // <-- change this

documentation/antora.yml

Update the version, display_version, and the plugin-version attribute:

version: '0.3.0'         # <-- new version
display_version: '0.3.0'
asciidoc:
  attributes:
    plugin-version: '0.3.0'
    nextflow-min-version: '24.10.0'
    libbids-sh-version: 'v3.0'

Evidence: Running ./gradlew properties | grep ^version should print the new version string. Failure mode: If build.gradle and antora.yml are out of sync, the published plugin and the published documentation will advertise different version numbers — confusing users.

Step 2 — Changelog Update

Add a section for the new version at the top of CHANGELOG.md, following the existing format:

## [0.3.0] - YYYY-MM-DD

### Added
- ...

### Changed
- ...

### Fixed
- ...

Move all [Unreleased] entries into the new section.

Evidence: The changelog section clearly documents every user-visible change so that adopters can assess the upgrade impact. Failure mode: Releasing without a changelog entry leaves adopters with no migration context.

Step 3 — Test and Validation Pass

Run the full test suite. Every layer must pass before proceeding.

# Layer 1: unit tests
./gradlew test

# Layer 2: integration / validation
cd test/validation && bash test_datasets.sh && cd ../..

# Layer 3: edge cases
cd test/edge_cases && bash run_all_tests.sh && cd ../..

# Layer 3b: benchmark workflow
act workflow_dispatch -W .github/workflows/benchmark.yml -j benchmark

See the Testing Guide for details on what each layer verifies.

Evidence: Zero test failures across all layers. Failure mode: Any failing test must be fixed before creating a tag. Shipping a broken release destroys user trust and may require an emergency patch release.

Step 4 — Documentation Build Pass

./gradlew docs
# or equivalently:
make docs

This generates the API reference, renders PlantUML diagrams, and builds the full Antora site. Browse documentation/build/site/ locally (using make docs-serve) and confirm:

  • The new version number appears in the site header.

  • All xref cross-links resolve without Antora warnings.

  • Diagrams render correctly.

  • The GroovyDoc API reference reflects any new public methods.

Evidence: A clean ./gradlew docs run with no errors and the new version visible in the site. Failure mode: Broken xrefs, missing diagrams, or malformed AsciiDoc abort the build. Fix all Antora/PlantUML errors before proceeding.

Step 5 — Git Tag

Commit the version-bump and changelog changes:

git add build.gradle documentation/antora.yml CHANGELOG.md
git commit -m "chore: release {plugin-version}"

Create an annotated tag:

git tag -a v{plugin-version} -m "Release {plugin-version}"
git push origin main --follow-tags

Evidence: The tag appears on the GitHub repository’s Releases page. Failure mode: Pushing without --follow-tags leaves the tag only in the local repository. A missing tag means the automated publication step (below) is never triggered.

Step 6 — Plugin Publication

make release
# equivalent to:
./gradlew releasePlugin

The releasePlugin task is provided by the io.nextflow.nextflow-plugin Gradle plugin (version 1.0.0-beta.10, see build.gradle). It packages the plugin and submits it to the Nextflow Plugin Registry.

Evidence: The new version appears at https://registry.nextflow.io/plugins/nf-bids after the task completes. Failure mode: Authentication errors (missing registry credentials) cause the task to fail without publishing. Ensure your Nextflow plugin registry token is set in the environment or gradle.properties (see the io.nextflow.nextflow-plugin plugin documentation for the required property name).

Step 7 — Documentation Publication (Automated)

The CI workflow .github/workflows/docs.yml is planned for a later implementation phase. Until it is added, documentation must be published manually (run ./gradlew docs and push the documentation/build/site/ artefact to the gh-pages branch, or upload to your hosting provider).

Intended automated flow: When a tag matching v* is pushed to main, the docs.yml workflow will:

  1. Checkout the tagged commit with submodules.

  2. Run ./gradlew docs to produce documentation/build/site/.

  3. Deploy the site to GitHub Pages (target: https://nf-neuro.github.io/nf-bids).

Evidence (once implemented): A green docs workflow run on the Actions page and the updated site live at the published URL. Failure mode: A failing ./gradlew docs step in CI indicates a documentation regression that was not caught locally. Always run make docs locally before pushing the release tag.

Release Checklist

[ ] build.gradle version bumped
[ ] documentation/antora.yml version / attributes bumped
[ ] CHANGELOG.md updated with new section
[ ] ./gradlew test — all unit tests green
[ ] cd test/validation && bash test_datasets.sh && cd ../.. — all integration tests green
[ ] cd test/edge_cases && bash run_all_tests.sh && cd ../.. — edge cases green
[ ] act workflow_dispatch -W .github/workflows/benchmark.yml -j benchmark — benchmark workflow green
[ ] ./gradlew docs — site builds cleanly, version correct in header
[ ] Commit: "chore: release vX.Y.Z"
[ ] git tag -a vX.Y.Z pushed with --follow-tags
[ ] make release (./gradlew releasePlugin) — version visible on registry
[ ] docs.yml workflow triggered (or manual site deploy until CI is added)