Release process

This is the maintainer cut. .github/workflows/release.yml only runs gh release create when a v* tag is pushed. Versions, newsfragments, bindings wraps, and the Zenodo pin are not automated.

d-SEAMS is five packages:

repo

product

seams-core

libyodaLib and seams

PydSEAMSlib

pydseams

yodaStruct

dseams Lua/Fennel

linkcell

periodic k-nearest neighbour search

dseams-plumed

DSEAMS_CAGES PLUMED action

Bindings do not live in seams-core. -Dwith_python=true and -Dwith_lua=enabled are Meson errors that name those repositories. Do not add a language binding here. Do not resurrect yodaStruct -c or conf.yaml.

Checklist

  1. Feature work is on main, or on a native GitHub stack that lands on main.

  2. CI is green on the merge commit (CI and Docs).

  3. Collect Keep a Changelog fragments under changelog.d/ that are not already in CHANGELOG.md. Name each file +slug.added.md (or changed, deprecated, removed, fixed, security). Fragments whose text is already in CHANGELOG.md reprint those notes if they stay in the directory. Then:

    towncrier build --version X.Y.Z

    That writes CHANGELOG.md and removes the consumed fragments.

  4. Bump pixi.toml, meson.build, and CITATION.cff together. Pass --version X.Y.Z to towncrier; do not store a stale version in towncrier.toml. Sync docs/orgmode/changelog.org with the new CHANGELOG.md section. nix/package.nix and docs/source/Doxyfile_seams.cfg PROJECT_NUMBER also carry a version string; do not leave them behind the cut.

  5. Export org docs with pixi run -e docs docbld (same command as the contributing page and ci_docs.yml). Org under docs/orgmode/ is the source. RST under docs/source/ is generated and is not committed.

  6. Open a chore: cut X.Y.Z pull request. Merge when CI is green.

  7. Tag vX.Y.Z on d-SEAMS/seams-core and push the tag. release.yml mints the GitHub release (gh release create --generate-notes).

  8. Point PydSEAMSlib and yodaStruct subprojects/seams-core.wrap revision at that tag. Bump those package versions to the same X.Y.Z when the wrap is the only change. When the wrap stays and a front end binds new engine surfaces, cut a frontend-only minor: keep the wrap tag, bump the package version, and tag that repository. Tag those repositories on their own schedule.

  9. Zenodo: run repro/stage_zenodo.sh and pin the software in that record to the release tag, never a commit. Do not mint a new DOI version for prose. See repro/zenodo/README.md.

  10. GitHub native stacked PRs are same-repo only. Use gh stack link to attach PRs and gh stack merge to land them. Cross-fork stacks are not supported. Merge-top lands the whole stack. Use gh stack merge (async stack merge), not a lone gh pr merge of a mid-stack PR, if the stack object is to stay intact.

Version files

seams-core cut:

file

field

meson.build

project(..., version:)

pixi.toml

[workspace] version

CITATION.cff

version

CHANGELOG.md

towncrier output for X.Y.Z

docs/orgmode/changelog.org

new section from CHANGELOG.md

nix/package.nix

version

docs/source/Doxyfile_seams.cfg

PROJECT_NUMBER

Front ends, after the engine tag exists:

file

field

subprojects/seams-core.wrap

revision = vX.Y.Z

PydSEAMSlib pyproject.toml, meson.build, CITATION.cff

package version

PydSEAMSlib docs/source/conf.py

release

yodaStruct meson.build, CITATION.cff

package version

yodaStruct docs/source/conf.py

release

Newsfragments

One file for each user-visible change, under changelog.d/, named +slug.<type>.md or <github-issue>.<type>.md. Types are the Keep a Changelog set: added, changed, deprecated, removed, fixed, security. Write the fragment in the same pull request as the change. The cut in step 3 consumes only fragments that are not already reflected in CHANGELOG.md. Every d-SEAMS package uses this layout.