Step 2 · Release

Goal

Cut the release, deploy to production, and confirm the system is healthy.

Instructions

You are in workflow step 2 of the release-cycle. Pre-release checks have passed. Now ship it.

Tasks to Perform

1. Determine the Version Number

Based on the changes in this release:

  • Bug fixes only → bump PATCH: 1.2.3 → 1.2.4
  • New features, backward compatible → bump MINOR: 1.2.3 → 1.3.0
  • Breaking changes → bump MAJOR: 1.2.3 → 2.0.0
# Confirm the previous version
git tag -l --sort=-creatordate | head -3

2. Update CHANGELOG.md

Change ## [Unreleased] to the version being released:

## [1.3.0] — 2026-03-28

### Added
- [Feature name]: description of what users can now do

### Changed
- [What changed]: how behaviour is different  

### Fixed
- [Bug description]: what was wrong and is now corrected

### Security
- Updated [package] to address CVE-XXXX-XXXX

3. Commit the Release

git add CHANGELOG.md
git commit -m "chore: release v1.3.0"

4. Tag the Release

git tag -a v1.3.0 -m "Release v1.3.0"
git push origin main
git push origin v1.3.0

5. Run Database Migrations

If this release includes database migrations:

# Run on staging first, verify, then production
# Staging:
[migration command] --env=staging

# Verify staging is healthy after migration
curl -s https://staging.app/health/ready | head -5

# Production (only after staging is verified):
[migration command] --env=production

⚠️ If a migration fails in production, do NOT proceed with the code deploy. Restore the database to pre-migration state before proceeding.

6. Deploy the Application

Trigger the deployment pipeline:

# If using a CI/CD system, trigger via tag push (done in step 4)
# If deploying manually:
[deployment command] --version=v1.3.0

7. Monitor Deployment Progress

Watch for:

  • [ ] Build succeeds
  • [ ] Deploy succeeds
  • [ ] Health check GET /health/ready returns 200
  • [ ] No error spike in the first 5 minutes
# Monitor error rate during and after deploy
tail -f [production log] | grep "ERROR\|WARN" &

# Tail health check
watch -n 5 "curl -s https://app/health/ready"

8. Post-Deploy Smoke Test

Immediately after deployment, manually verify the critical paths work:

  • [ ] Application loads (HTTP 200 on main page or root API)
  • [ ] Login works
  • [ ] The primary new feature in this release is accessible
  • [ ] Any fixed bugs are confirmed fixed

Rollback Procedure

If the deployment fails or causes errors:

# Option A: Revert via deployment platform to previous version
[platform-specific rollback]

# Option B: Revert the git commit and redeploy
git revert HEAD
git push origin main
[re-trigger deployment]

# Option C: Emergency patch
git checkout -b hotfix/v1.3.1
# make the minimal fix
# follow the expedited release process

After rollback:

  1. Verify health check is green
  2. Confirm error rate is back to baseline
  3. Document what went wrong in a post-mortem issue
  4. Fix the issue before re-attempting the release

Exit Criteria

This step is complete when:

  • [ ] Version tag exists in git
  • [ ] CHANGELOG.md updated
  • [ ] Code deployed to production
  • [ ] All health checks green
  • [ ] No elevated error rate 10 minutes post-deploy
  • [ ] Smoke tests passing
  • [ ] Ready to proceed to Step 3 (Post-Release)