template/docs/release-process.md

Release Process

This document defines the default release process.

For daily delivery flow, see workflow.md. For branch policy, see branching.md. For release checklist, see CHECKLISTS.md.

Release Principles

• Release small changes when practical.
• Prefer repeatable automation over manual steps.
• Validate before and after deployment.
• Keep rollback or recovery options ready.
• Record production-impacting decisions.

Release Types

Type	Description	Example
Standard	Planned release through the normal pipeline.	Weekly feature release.
Hotfix	Urgent production fix.	Authorization regression fix.
Experimental	Limited rollout or feature flag release.	Beta feature for selected users.
Infrastructure	Runtime, hosting, network, or dependency change.	Database engine upgrade.

Versioning

Choose the versioning model that matches the project:

• Semantic versioning for libraries, APIs, SDKs, and installable packages.
• Calendar versioning for operational products with frequent releases.
• Build numbers or commit SHAs for internal services.

Document the chosen model in PROJECT.md.

Readiness

Before release:

• Scope is confirmed.
• Required checks pass.
• Migrations are reviewed.
• Configuration is ready.
• Secrets are present in the target environment.
• Rollback or recovery plan exists.
• Monitoring is available.
• Stakeholders know the release window when needed.

Deployment

Deployment steps:

1. Confirm target environment.
2. Confirm release version or commit.
3. Run pre-deploy checks.
4. Deploy.
5. Run migrations when required by the release plan.
6. Run smoke tests.
7. Monitor health and error signals.
8. Announce completion or rollback.

Smoke Tests

Smoke tests should prove that the release is alive and the most important path works.

Examples:

• Health endpoint returns success.
• Application loads.
• Login works.
• Critical API endpoint succeeds.
• Background worker starts.
• Database connectivity is healthy.

Rollback And Recovery

Rollback planning should address:

• Application artifact rollback.
• Database migration rollback or forward fix.
• Configuration rollback.
• Feature flag disablement.
• Queue or job replay behavior.
• External dependency failure.

If database changes are not reversible, document the recovery path before deployment.

Post-Release Review

After release:

• Confirm monitoring is quiet or expected.
• Record incidents or anomalies.
• Update docs if release steps drifted.
• Add follow-up tasks for manual work discovered during release.
• Capture lessons in checklists or ADRs when they change future behavior.