Handling a Regression
This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in RFC 2119 to indicate requirement levels.
This playbook guides SDK maintainers through handling regressions discovered after a release. It covers severity assessment, response options (patch release vs. rollback), communication protocols, and post-incident review. By following these steps, regressions will be resolved quickly with minimal user impact.
Related resources:
- Post-release monitoring — how regressions are detected
- Rollback procedures — emergency rollback process
- Cutting a Release — standard release process (expedited for patches)
Classify the regression using these criteria:
- Critical (crashes, data loss, security vulnerability) → patch release MUST be cut within 48 hours
- High (broken feature, significant performance degradation) → patch release SHOULD be cut within 1 week
- Medium (edge case, cosmetic issue) → fix MAY be included in next regular release
You MUST take one of the following actions:
Option A: Revert and patch
- Revert the problematic commit(s) on a release branch
- Use the revert commit format:
revert: <original commit subject> - Cut a patch release following Cutting a Release, expedited — you MAY skip non-essential gates for critical severity
Option B: Yank the release
- If a clean revert isn't possible, yank the bad release from the package registry
- Follow the documented rollback procedure: Rollback procedures
You MUST post a GitHub issue describing:
- What happened (brief explanation of the regression)
- Which versions are affected
- What users should do (pin to previous version, or upgrade to the patch)
Document the incident for the quarterly retrospective:
- What happened
- How it was caught (or why it wasn't caught in testing)
- What would have prevented it
This helps identify gaps in testing, review processes, or monitoring that can be improved.
- Post-release monitoring — monitoring that detects regressions
- Rollback procedures — emergency rollback process
- Release Gating Criteria — gates that may be expedited for critical patches
| Version | Date | Summary |
|---|---|---|
1.0.0 | 2026-02-23 | Initial playbook — regression response with severity assessment and expedited patch process |
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").