Release Process

This is the source-of-truth runbook for making a new HestiaStore release.

For contribution workflow, community standards, and project history, use Contribute and Community.

For day-to-day branch selection, task worktrees, and pull request targeting, use Git and Worktree Workflow. This page covers the release-specific exception: a clean dedicated main worktree.

Branching model

Branching and release flow

Normal work starts from devel, merges back to devel, and reaches main through the release flow. Hotfixes start from main, merge back to main, and must then be synced into devel.

When you ask Codex to use the release-maven-library skill, it performs the full local release workflow described on this page: prerequisite checks, pre-release verification, release version bump, release commit, release tag, Maven Central deployment, next snapshot bump, next snapshot commit, and Git pushes.

The only manual step is publishing the GitHub release on the repository homepage at https://github.com/jajir/HestiaStore/releases. Codex can prepare the release title and body, but it cannot click Publish release in the GitHub web UI.

If you are using Codex in this repository, use the release-maven-library skill. The skill follows the same workflow documented here and uses the helper scripts under .agents/skills/release-maven-library/scripts/.

Release Principles

Keep release work focused on release and versioning changes only.
Do not mix unrelated refactors, dependency upgrades, or API changes into a release commit.
Stop immediately if the working tree is dirty, the current version is inconsistent, a forbidden snapshot dependency is found, or verification fails.

Versioning

Hestia Store uses Semantic Versioning:

X.Y.Z

X: major version for incompatible API changes
Y: minor version for backward-compatible feature work
Z: patch version for backward-compatible fixes

Development versions use the -SNAPSHOT suffix:

X.Y.Z-SNAPSHOT

Release preparation should start from a snapshot version and convert it to the matching release version.

Releases are published to Maven Central. Release credentials and signing configuration live in ~/.m2/settings.xml.

Releases must be prepared from a clean main branch worktree with push access to the repository and tags.

Prerequisites

Java 17 and Maven are installed.
You are in the repository root.
The branch and working tree are clean.
Maven Central credentials are configured in ~/.m2/settings.xml.
GPG signing is configured for the Maven release profile.

Example settings.xml fragments:

<settings>
  <servers>
    <server>
      <id>central</id>
      <username>YOUR_USERNAME</username>
      <password>YOUR_TOKEN</password>
    </server>
  </servers>

  <profiles>
    <profile>
      <id>release</id>
      <properties>
        <gpg.executable>gpg</gpg.executable>
        <gpg.passphrase>YOUR_GPG_PASSPHRASE</gpg.passphrase>
      </properties>
    </profile>
  </profiles>
</settings>

Generate the Maven Central credentials from your account at central.sonatype.com, make sure the org.hestiastore namespace is verified for that account, and confirm a usable GPG secret key exists locally before starting a release.

Release Checklist

Verify the working tree is clean and the release is being prepared from main.
Detect the current Maven version.
Confirm the current version is a snapshot.
Run ./.agents/skills/release-maven-library/scripts/verify-release.sh.
Confirm there are no forbidden snapshot dependencies or plugins.
Bump from X.Y.Z-SNAPSHOT to X.Y.Z.
Run verification again after the release version change.
Commit and tag the release.
Run mvn -P release -DskipTests verify.
Deploy the release artifact from the repository root.
Push the release commit and tag.
Bump to the next snapshot version.
Verify again after the next snapshot bump.
Push the post-release snapshot commit.
Publish the GitHub release manually.

Step-by-Step Procedure

1. Checkout and update the `main` branch

Release work is the main branching exception to the normal devel flow. Start from a clean main worktree and fast-forward it before changing versions:

git checkout main
git pull --ff-only
git status --short --branch

If the working tree is not clean, stop and resolve that first.

2. Detect the current project version

Run:

mvn help:evaluate -Dexpression=project.version -q -DforceStdout

Expected result:

X.Y.Z-SNAPSHOT

If the version does not end with -SNAPSHOT, do not continue with release preparation until the intended state is clear.

3. Run pre-release verification

Use the helper script:

./.agents/skills/release-maven-library/scripts/verify-release.sh

That script runs the standard release verification used by the skill. If verification fails, stop and fix the problem before changing versions.

4. Check for forbidden snapshot dependencies or plugins

Search all Maven project files for snapshot versions:

rg -n --glob 'pom.xml' 'SNAPSHOT'

Before the release bump, the current project version is expected to appear as a snapshot. Any unrelated snapshot dependency, plugin, or version property is a release blocker and must be removed or intentionally approved before continuing.

5. Prepare the release version

Convert X.Y.Z-SNAPSHOT to X.Y.Z using the helper script:

./.agents/skills/release-maven-library/scripts/bump-version.sh X.Y.Z

Review the changed pom.xml files, then verify again:

./.agents/skills/release-maven-library/scripts/verify-release.sh
rg -n --glob 'pom.xml' 'SNAPSHOT'
git status --short

After the release bump, there should be no remaining forbidden snapshot versions in the Maven project files.

6. Commit and tag the release

Review the changed files and create a focused release commit:

git add pom.xml */pom.xml
git commit -m "release: version X.Y.Z"
git tag release-X.Y.Z

Use the release-X.Y.Z tag format. Create the tag on the release commit, not on the later post-release snapshot commit.

7. Validate the release profile

Run the root release profile so the parent POM and all release modules are validated together:

mvn -P release -DskipTests verify

Do not deploy engine alone. The release must be run from the repository root so the parent POM and all publishable modules stay aligned.

The benchmarks module participates in the build but is not deployed because its POM sets maven.deploy.skip=true.

8. Deploy the release

Deploy the release to Maven Central from the repository root:

mvn -P release -DskipTests deploy

9. Push the release commit and tag

After deployment succeeds, push both the branch and the release tag:

git push origin main
git push origin release-X.Y.Z

10. Prepare the next development snapshot

After the release is deployed, bump to the next snapshot version:

./.agents/skills/release-maven-library/scripts/prepare-next-snapshot.sh X.Y.(Z+1)-SNAPSHOT
./.agents/skills/release-maven-library/scripts/verify-release.sh
git add pom.xml */pom.xml
git commit -m "post-release: bumped to X.Y.(Z+1)-SNAPSHOT"
git push origin main

11. Publish the release on GitHub

This step is manual and must be completed on the GitHub repository homepage, not in the generated documentation site:

Go to https://github.com/jajir/HestiaStore/releases and choose Draft a new release.
Select the existing tag release-X.Y.Z.
Keep main as the target branch.
Set the release title to Release X.Y.Z.
In the description, include notable changes, any migration or compatibility notes, and the dependency snippet below.
If the release contains breaking changes, add a dedicated Breaking changes section with migration steps.
Press Publish release.

Suggested dependency snippet:

<dependencies>
  <dependency>
    <groupId>org.hestiastore</groupId>
    <artifactId>engine</artifactId>
    <version>X.Y.Z</version>
  </dependency>
</dependencies>

Helper Commands

Display dependency updates:

mvn versions:display-dependency-updates

Set a version manually without backup POMs:

mvn versions:set -DnewVersion=1.0.1-SNAPSHOT -DgenerateBackupPoms=false -DprocessAllModules=true

.agents/skills/release-maven-library/SKILL.md
.agents/skills/release-maven-library/references/release-checklist.md
AGENTS.md