Releasing#

How a Groundnote version gets from main to the image and the release page.

Versions#

Groundnote follows Semantic Versioning. Before 1.0.0 the API, the config and the data format may change: a minor version (0.2.0) can break things and says so in the changelog under a breaking-change entry; a patch version (0.1.1) never does. Scope files are migrated forward, and the changelog names any step a person has to take.

Tags have the form vMAJOR.MINOR.PATCH, with an optional pre-release suffix (v0.2.0-rc.1). A tag with a suffix becomes a pre-release on GitHub and does not move the major.minor image tag.

Who releases#

A maintainer from MAINTAINERS.md creates the tag. The release environment holds the image and the release page until a maintainer approves the run.

Steps#

1. Make sure main is green.

2. In a pull request:

   • set the version in package.json, and in server.json in the field version and in the tag of packages[0].identifier;
   • in CHANGELOG.md, move the entries under [Unreleased] into a new section ## [X.Y.Z] - YYYY-MM-DD and add its compare link at the bottom. The release notes are read from that section, so the heading has to match the tag;
   • for 0.1.0 only: remove the "unreleased" wording from the badge and the Quickstart and Status sections of README.md, from README.de.md, and from the Quickstart and Status texts in site/src/content/. The Quickstart can then use the published image.

3. After the merge, tag the merge commit and push the tag:

   git switch main && git pull --ff-only
   git tag -s vX.Y.Z -m "Groundnote X.Y.Z"
   git push origin vX.Y.Z

4. Approve the release environment in the Actions run. The workflow (.github/workflows/release.yml) first checks that the tag matches package.json, server.json and the changelog. Then it pushes ghcr.io/groundnote/groundnote for linux/amd64 and linux/arm64 with SBOM and provenance attestations, and creates the GitHub Release with the notes from the changelog.

5. For the first release only, set the package to public in the organisation's Packages → Package settings. Until then docker pull needs a login and the MCP Registry cannot read the image label.

6. Check the result:

   docker pull ghcr.io/groundnote/groundnote:X.Y.Z
   docker buildx imagetools inspect ghcr.io/groundnote/groundnote:X.Y.Z --format '{{json .Provenance}}'

7. Publish the new version to the MCP Registry:

   mcp-publisher login dns --domain groundnote.dev --private-key "$MCP_PUBLISHER_KEY"
   mcp-publisher publish

   The name dev.groundnote/groundnote is proved through a DNS TXT record on groundnote.dev (v=MCPv1; k=ed25519; p=…). The private key stays with the maintainer. The image carries the same name in its io.modelcontextprotocol.server.name label, which the registry checks.

If something goes wrong#

A tag that has been pushed stays. Fix the problem on main and release the next patch version; do not move a tag or overwrite an image. If a release has a security problem, mark it as such on the release page and publish an advisory as described in SECURITY.md.