Release Management

Release Management

This skill activates when a practitioner needs to plan, coordinate, or govern a Salesforce release cycle — covering version numbering schemes, rollback strategy, release notes generation, go/no-go criteria, and release calendar alignment with Salesforce's three seasonal platform releases per year.

Before Starting

Gather this context before working on anything in this domain:

• Determine whether the project is org-based (change sets, SFDX org-deploy) or artifact-based (unlocked packages, 2GP managed packages). Version numbering and rollback differ fundamentally between the two.
• Confirm the Salesforce seasonal release schedule. Salesforce releases three times per year (Spring, Summer, Winter). Sandbox preview opens approximately 4–6 weeks before the production release weekend. Changes deployed just before preview may be disrupted by platform changes.
• Identify which environments are in scope: production org, Full/Partial/Developer sandboxes, scratch orgs. Each has different data and metadata state implications for rollback.

Core Concepts

Seasonal Platform Releases and Sandbox Preview

Salesforce delivers three named releases per year (e.g., Spring '25, Summer '25, Winter '26). Each release upgrades all production orgs on a staggered weekend schedule (NA pods first, then EMEA, then APAC). Before production upgrade, Salesforce opens a sandbox preview window — typically 4–6 weeks before the production weekend. Orgs opted into preview receive the new release early.

Practical impact: any release you plan to deploy to production in the 2-week window immediately preceding the production upgrade weekend is high risk. Test in a preview sandbox if your deployment overlaps with a platform upgrade.

Versioning Schemes by Deployment Model

Org-based projects (change sets, sf project deploy start): The platform has no native version number for org metadata. Teams must define their own convention. Common approaches:

• Git tag with vYYYY.MM.DD-N (date + sequence)
• Jira/Linear release milestone label
• Custom object to track deployed versions

Unlocked packages: Version numbers are Major.Minor.Patch.Build. Only Major.Minor.Patch are user-controlled; Build auto-increments. The sf package version create command creates a new immutable version. The version ancestry is linear — you cannot branch and merge package versions.

2GP managed packages: Same Major.Minor.Patch.Build scheme. Patch versions require a patch org created from the specific version being patched (sf package version create --package-id 04t...).

Rollback Strategy

Salesforce has no native undo button for metadata deployments. Rollback means:

1. Pre-deploy: retrieve and archive the current state of every component you are deploying.
2. Post-deploy failure: redeploy the archived version.
3. For org-based: run sf project deploy start --manifest pre-release-backup.xml pointing at your archived source.
4. For unlocked packages: install the prior qualified package version with sf package install --package 04t<prior-version-id>.

Data changes made by the released code cannot be rolled back by redeploying metadata. Identify data mutations in your release notes and plan compensating data fixes if rollback is needed.

Go/No-Go Criteria

A go/no-go gate blocks deployment unless defined criteria pass. Typical criteria:

• All Apex tests pass with ≥75% org-wide coverage (RunLocalTests) or ≥75% per-class/trigger coverage (RunSpecifiedTests).
• Smoke test checklist passes in a Full sandbox that mirrors production.
• Zero open Severity 1 defects from UAT.
• Deployment validation (sf project deploy validate) completed successfully within the last 10 days (enables Quick Deploy).
• Release notes reviewed and signed off by product owner.

Common Patterns

Validation Deploy + Quick Deploy

When to use: Large orgs where running full Apex test suite takes 30–90 minutes. You want deployment weekend to be fast.

How it works:

1. Run sf project deploy validate --source-dir force-app --test-level RunLocalTests --async against production before the go-live window (within 10 days).
2. Save the returned deploy ID.
3. On deployment night, run sf project deploy quick --job-id <validatedDeployID> — this skips the full test run and completes in minutes.

Why not just deploy directly: Validation gives you a rehearsal. If it fails, you have days to fix. If you deploy directly and it fails at 2am, you are in a crisis.

Freeze Window Coordination

When to use: Shared production org with multiple teams and competing deployment schedules.

How it works:

1. Publish a release calendar with named code freeze dates. Code freeze = no new feature branch merges to main/release.
2. Only hotfixes (P1/P2) are allowed after code freeze.
3. Define the freeze period: typically 3–5 business days before deployment weekend.
4. Use a shared DevOps Center pipeline or a Jira board column to signal freeze status.

Rollback trigger: Define trigger conditions in writing before deployment begins — for example: "If any Apex test fails in production post-deploy, or if >3 Sev-1 defects are raised within 2 hours, rollback is initiated."

Decision Guidance

Recommended Workflow

1. Confirm deployment model (org-based vs package-based) and define the versioning convention for this project before any release is cut.
2. Check the Salesforce release calendar at trust.salesforce.com and flag any overlap between your planned deployment date and the seasonal upgrade weekend.
3. Build the release notes from the component list: list each component changed, the reason for the change, and any data migration steps.
4. Run a validation deploy (sf project deploy validate) against production at least 3 days before go-live. Resolve all failures.
5. Conduct UAT sign-off in a Full sandbox with the exact build being deployed. Close Sev-1 and Sev-2 defects before proceeding.
6. Execute deployment using Quick Deploy if within 10-day window; otherwise re-run full deploy.
7. Execute the post-deploy smoke test checklist and confirm all go/no-go criteria pass. If a rollback trigger fires, redeploy the pre-release archived version immediately.

Review Checklist

• Version number is defined and recorded in git tag / release notes / version tracking object
• Salesforce upgrade weekend checked against planned deployment date
• Validation deploy passed against production within the last 10 days
• UAT completed with full sign-off; zero open Sev-1 defects
• Rollback archive retrieved and stored before deployment begins
• Post-deploy smoke test checklist executed and all checks pass
• Release notes distributed to stakeholders before go-live

Salesforce-Specific Gotchas

1. Quick Deploy uses a new deploy ID — the sf project deploy quick command returns a NEW deploy request ID, not the validation ID. Monitor the new ID for status. Teams that poll the old validation ID will see it as Succeeded (it was) while the actual quick deploy is running.
2. RunSpecifiedTests is stricter than RunLocalTests — when you specify individual test classes, Salesforce requires 75% coverage per class AND per trigger in the deployed package, not just org-wide. This catches coverage gaps that RunLocalTests would miss.
3. Sandbox preview opt-in is per-sandbox — only sandboxes explicitly opted into the preview release receive it early. Your development sandbox may be on the new release while production is still on the prior one, causing metadata shape mismatches if you deploy preview-era metadata to a non-preview production.
4. Rollback cannot undo data changes — redeploying previous metadata does not reverse DML executed by the released code. Document every data mutation in release notes and prepare compensating scripts.

Output Artifacts

Related Skills

• devops/post-deployment-validation — validation deploy mechanics and Quick Deploy commands
• devops/change-set-deployment — org-based deployment when SFDX is not in use
• devops/continuous-integration-testing — automated test execution in CI, coverage gates
• devops/environment-strategy — sandbox strategy and environment topology decisions