Skip to content

RELEASE_WORKFLOW.md

Latest commit

 

History

History
134 lines (94 loc) · 3.35 KB

RELEASE_WORKFLOW.md

File metadata and controls

134 lines (94 loc) · 3.35 KB
Raw

Release Workflow

This document describes the recommended release workflow for the Cheesebox project. This is a suggestion for internal teams and contributors - adapt it to fit your needs.

Branch Structure

feature branches → dev (via PRs) → release branch → main (release PR)
Branch Purpose
main Production-ready code, tagged releases
dev Integration branch for ongoing work
release/x.x.x Temporary branch for preparing releases

Day-to-Day Development

  1. Create feature/fix branches from dev
  2. Open PRs targeting dev
  3. Review and merge PRs into dev
  4. Don't update changelog yet - changes are "in flight"

Creating a Release

When ready to release:

Step 1: Find the last release tag

git tag --sort=-v:refname | head -1

This returns your most recent tag (e.g., v1.8.1). You'll need this to see what changed.

Step 2: Review changes since last release

# Replace v1.8.1 with your actual last tag from Step 1
git log v1.8.1..dev --oneline --no-merges

Step 3: Create the release

# Create release branch from dev
git checkout dev && git pull
git checkout -b release/1.9.0

# Bump version in package.json
npm version minor --no-git-tag-version  # or patch/major

# Update CHANGELOG.md with the changes you reviewed in Step 2

# Commit version bump and changelog
git add package.json package-lock.json CHANGELOG.md
git commit -m "v1.9.0"

# Push and create PR into main
git push -u origin release/1.9.0
gh pr create --base main --title "v1.9.0" --body "Release v1.9.0 - See CHANGELOG.md for details."

After Merging to Main

Merge the PR via the GitHub web UI, then run these commands locally:

# Tag the release
git checkout main && git pull
git tag v1.9.0
git push --tags

# Sync dev with main
git checkout dev
git merge main
git push

Quick Reference

Step Branch Changelog Version
Feature PRs → dev No No
Create release branch release/x.x.x Update Bump
Release PR → main Already done Already done
After merge main Tag only —
Sync back main → dev — —

Versioning

This project follows Semantic Versioning:

  • MAJOR (1.0.0 → 2.0.0): Breaking changes
  • MINOR (1.0.0 → 1.1.0): New features, backwards compatible
  • PATCH (1.0.0 → 1.0.1): Bug fixes, backwards compatible

Changelog Format

The changelog follows Keep a Changelog format:

## [1.9.0] - 2026-01-28
### Added
- New features

### Changed
- Changes to existing functionality

### Fixed
- Bug fixes

### Security
- Security improvements

Useful Git Commands

# Find your latest tag
git tag --sort=-v:refname | head -1

# List all tags
git tag --sort=-v:refname

# See commits since a tag (replace v1.8.1 with your tag)
git log v1.8.1..dev --oneline --no-merges

# See which files changed since a tag
git diff v1.8.1..dev --stat

# See full diff of changes
git diff v1.8.1..dev