Skip to content

RELEASING.md

Latest commit

 

History

History
141 lines (97 loc) · 4.15 KB

RELEASING.md

File metadata and controls

141 lines (97 loc) · 4.15 KB
Raw

Release Process

This document describes how AudioBlock Backend is versioned, tagged, and released.

Versioning Scheme

We follow Semantic Versioning 2.0.0:

Version bump When to use
MAJOR (x.0.0) Breaking API change, incompatible DB schema change, or contract ABI breaking change
MINOR (1.x.0) New backwards-compatible feature or endpoint
PATCH (1.0.x) Bug fix, security patch, dependency update, docs, refactor

The bump is determined automatically by the labels on merged PRs (see PR Labels).
When multiple PRs are in the batch, the highest-precedence bump wins.

PR Labels

Apply one of these labels to every PR before merging. Release Drafter uses them to:

  1. Categorise entries in the release notes draft
  2. Resolve the next semver version automatically
Label Bump Changelog section
breaking-change major — (triggers major bump)
feature / enhancement minor 🚀 Features
bug / fix patch 🐛 Bug Fixes
performance patch ⚡ Performance
security patch 🔒 Security
blockchain / soroban / stellar patch 🔗 Blockchain / On-Chain
infrastructure / docker / ci patch 🏗 Infrastructure
documentation / docs patch 📝 Documentation
chore / dependencies / refactor patch 🧹 Chores & Maintenance
skip-changelog — PR excluded from draft
wip — PR excluded from draft

Release Workflow

1. Ongoing — label every merged PR

Ensure each PR merged into main carries the correct label (see table above).
The Release Drafter GitHub Action updates the draft release automatically after every merge.

2. Pre-release — review the draft

  1. Go to GitHub → Releases → Drafts.
  2. Open the current draft (e.g. v1.2.0).
  3. Review and edit the generated notes:
    • Correct any misclassified entries.
    • Add context for breaking changes.
    • Remove internal/noise entries (or label those PRs skip-changelog and re-run the workflow).
  4. Confirm the auto-resolved version is correct. Override it manually in the tag field if needed.

3. Bump package.json

# Example for a minor release
npm version minor --no-git-tag-version
# or patch / major as appropriate

Commit the bump on main (or as the last commit on the release PR):

git add package.json
git commit -m "chore: bump version to v$(node -p "require('./package.json').version")"

4. Update CHANGELOG.md

Move the [Unreleased] section content into a new dated version section:

## [1.2.0] - YYYY-MM-DD

### Added
...

## [Unreleased]
(empty — ready for next batch)

Add the comparison link at the bottom:

[1.2.0]: https://github.com/Darkvader-ship-it/AudioBlock_Backend/compare/v1.1.0...v1.2.0

5. Publish the GitHub Release

  1. In the draft release, set the tag to v<version> (e.g. v1.2.0), targeting main.
  2. Click Publish release — GitHub creates and pushes the tag automatically.

6. Verify

  • Confirm the new tag appears under Code → Tags.
  • Confirm the release shows in Releases (not Drafts).
  • Confirm CI passes on the tagged commit.

Hotfix Releases

For urgent patches on a live version:

git checkout -b hotfix/v1.1.1 v1.1.0
# make fix, commit with label `fix` or `security`
git push origin hotfix/v1.1.1
# open PR → merge → follow steps 2–6 above

Docker Images

After publishing a release tag, the Docker image should be rebuilt and pushed:

docker build -t audioblockbackend:v<version> .
docker tag audioblockbackend:v<version> audioblockbackend:latest

Update any deployment manifests to reference the new tag.

Alignment with CHANGELOG.md

  • CHANGELOG.md is the human-readable record maintained in the repository.
  • GitHub Releases (generated by Release Drafter) are the machine-readable record linked to git tags.
  • Both must be updated as part of every release (steps 4 and 5 above).
  • The [Unreleased] section in CHANGELOG.md is the source of truth between releases.