1

lessons/sprints/versioning-workflow---use-unreleased-and-release-script

Leo Miranda edited this page 2026-01-24 18:09:50 +00:00

Table of Contents

• Context
• Problem
• Solution
• Prevention
• Related

Context

Version drift was discovered where CHANGELOG.md had a [3.1.2] entry dated 2026-01-23, but no git tag existed. The marketplace.json was also out of sync.

Problem

The root cause was documenting changes under a versioned CHANGELOG section ([3.1.2]) before the release process was complete. This violates the Keep a Changelog standard where:

1. All work-in-progress goes under [Unreleased]
2. Versioned sections are only created at release time
3. Version must be consistent across: git tags, README, marketplace.json, CHANGELOG

Solution

Created a standardized versioning workflow:

1. During development: All changes go under [Unreleased] in CHANGELOG.md

2. At release time: Use ./scripts/release.sh X.Y.Z which:

   • Validates [Unreleased] has content
   • Renames [Unreleased] to [X.Y.Z] - YYYY-MM-DD
   • Updates README.md title
   • Updates marketplace.json version
   • Commits and creates git tag

3. Documentation: CLAUDE.md now includes versioning workflow with:

   • Version locations table
   • SemVer guidelines (PATCH/MINOR/MAJOR)
   • Development vs release workflows

Prevention

1. Never create versioned CHANGELOG sections manually - always use [Unreleased]
2. Use the release script - ensures atomic, consistent updates
3. SemVer discipline:
   • PATCH (x.y.Z): bug fixes only
   • MINOR (x.Y.0): new features
   • MAJOR (X.0.0): breaking changes

Related

• Issue: Investigate versioning inconsistency - CHANGELOG.md ahead of git tags (#143)
• Branch: fix/issue-143-versioning-workflow
• Release: v3.2.0
• Files: scripts/release.sh, CLAUDE.md, CHANGELOG.md

---

Tags: versioning, semver, changelog, release, workflow, documentation