Step 5 · Release

Goal

Ship the feature to production safely, with observability, a rollback plan, and a release record.

Instructions

You are in workflow step 5 of the feature-cycle. The feature is tested and ready. Now release it.

Pre-Release Checklist

Before triggering any deployment, verify every item:

Code quality

  • [ ] All tests pass on the release branch
  • [ ] No lint errors
  • [ ] No debug output in the code (console.log, var_dump, dd(), debugger)
  • [ ] No hardcoded secrets or environment-specific values

Completeness

  • [ ] All acceptance criteria from the spec are implemented and verified
  • [ ] CHANGELOG.md has an entry under [Unreleased] describing this feature
  • [ ] README.md is updated if public interface changed
  • [ ] Any required database migration is included and tested

Operational readiness

  • [ ] Environment variables required by this feature are documented in .env.example
  • [ ] The migration can be run without downtime (verified in §6 of the database-engineer agent)
  • [ ] Health checks still pass after migration

Release Steps

1. Update the Changelog

Move the [Unreleased] entries to a version heading:

## [1.3.0] — 2026-03-28

### Added
- Feature name: one-liner describing what users can now do

2. Create a Release Commit

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

3. Tag the Release

git tag -a v1.3.0 -m "Release v1.3.0 — [feature name]"
git push origin main --tags

4. Run the Database Migration (if required)

# Confirm you are connected to the correct environment
echo $APP_ENV   # must be production (or staging for staging deploy)

# Run migration — staging first, then production
[migration command]

# Verify migration succeeded
[check schema command]

5. Deploy

Trigger the deployment pipeline. Monitor:

  • Build succeeds
  • Health check passes post-deploy
  • No spike in error rate in the first 5 minutes
  • Verify the new feature is accessible

6. Post-Deploy Smoke Test

Manually exercise the happy path of the new feature in production (or staging) immediately after deployment:

  • [ ] The feature is accessible
  • [ ] The primary flow works end to end
  • [ ] No unexpected errors appear in logs
# Tail production logs during smoke test
tail -f [log path] | grep -E "ERROR|WARN|new-feature-identifier"

Rollback Plan

If the deployment causes errors or the feature is broken in production:

Rollback the code:

# Option 1: Revert the release commit
git revert HEAD
git push origin main
# Trigger redeployment

# Option 2: Roll back to previous image/version via your deployment platform
# [platform-specific rollback command]

Rollback the migration (if needed):

# Only if the migration is not yet in use by other features
[down/rollback migration command]

⚠️ WARNING: Rolling back a migration that ran on live data may cause data loss. Verify the rollback is safe before executing it.

Post-Release

  1. Monitor for 30 minutes — watch error rate, response times, and logs
  2. Update TODO.md — mark the feature-level tasks complete (- [x] YYYY-MM-DD [task]), remove from active backlog; any follow-up items should be added as new tasks with _(ref: workflows/feature-cycle/05-release.md)_
  3. Close the feature spec — add ## Status: Released in v1.3.0 to the top of docs/features/FEATURE-NAME.md
  4. Announce — notify stakeholders that the feature is live

Exit Criteria

This step is complete when:

  • [ ] Feature is deployed and verified in production
  • [ ] No elevated error rate 30 minutes post-deploy
  • [ ] Release tagged and changelog updated
  • [ ] Feature spec marked as released
  • [ ] TODO.md cleaned of completed tasks