Release Process

This document describes the step-by-step process for creating a new release of NeoPRISM.

Versioning

NeoPRISM follows Semantic Versioning (semver). The current version is stored in two places:

Prerequisites

Before starting a release, ensure you have:

• Write access to the hyperledger-identus/neoprism repository
• A GitHub personal access token with repo scope for pushing tags
• Conventional commits — all commits in the release should follow the Conventional Commits standard. PR titles are validated against the conventional commits format by .github/workflows/pr-lint.yml (using amannn/action-semantic-pull-request@v6), and git-cliff uses conventional commit messages to generate the changelog automatically.
• Nix — all release commands run inside nix develop

Release Steps

1. Ensure you are on the latest main branch

git checkout main
git pull origin main

2. Checkout the release branch

Create the release branch to the current main:

git checkout -b release

3. Bump the version

Run the automated version bump command from inside nix develop:

nix develop -c just release::bump-version

The release::bump-version recipe does all of the following automatically:

1. Determines the next version — uses git-cliff to compute the next version based on conventional commits since the last tag
2. Updates version and Cargo.toml — writes the new version to both files
3. Generates the changelog — runs git-cliff to rebuild CHANGELOG.md from the commit history
4. Regenerates Docker Compose configs — runs just build-config to update the auto-generated Docker Compose files with the new version

4. Commit the version bump

git add .
git commit -s -m 'chore(release): prepare for the next release'

5. Push and open a pull request

git push origin release

Open a pull request from release into main on GitHub. Once CI checks pass, merge the PR.

6. Create and push the tag

After the PR is merged to main, create a tag for the release and push it:

git checkout main
git pull origin main
VERSION=$(cat version)
git tag "v$VERSION"
git push origin "v$VERSION"

7. Trigger the release workflow

Note: The release workflow is triggered manually — it does not run automatically on tags.

Go to the Release workflow on GitHub Actions and click Run workflow. Enter the version number (without the v prefix) in the tag input field.

The workflow will:

1. Check out the tagged commit
2. Build Docker images for linux/amd64 and linux/arm64 using Nix
3. Create a multi-arch Docker manifest and push it to Docker Hub under $DOCKERHUB_ORG/identus-neoprism:<VERSION>

8. Release the docs

Trigger the Deploy Docs Site workflow manually to publish the updated mdBook site to GitHub Pages.

9. Create a GitHub Release

Navigate to the Releases page and click Draft a new release. Select the v<VERSION> tag.

Optional: Curate the notable changes or highlight the breaking changes or other notes which require attention.

10. Verify the release

• Docker Hub: Confirm the multi-arch image is available at docker pull $DOCKERHUB_ORG/identus-neoprism:<VERSION>
• GitHub Releases: Confirm the release is published on the Releases page
• Docs site: Confirm the updated documentation is live on GitHub Pages

Release workflow reference

The CI pipeline for releases is defined in .github/workflows/release.yml. Key details:

Related files