Software Development, Human Acceptance Testing and Safe Rollback
Fill in the bracketed placeholders for your project. Apply this workflow to releases and significant changes. Scale the depth of the checks to the change, the people affected and the consequences of failure.
1. Project Setup
| Item | Project details |
|---|---|
| Project and canonical source | [Project name], [Source repository] |
| Environments | [Development environment], [UAT environment], [Release environment] |
| Candidate and recovery records | [Build archive], [Recovery plan or runbook] |
| Human acceptance testers | [Named users or representatives] |
| Human release approver | [Named person or accountable role] |
| Recovery owner | [Named person or accountable role] |
| Recovery objectives | [Acceptable downtime], [Acceptable data loss] |
One person may hold multiple roles on a small project. Record who performs human UAT, who approves release and who can initiate recovery. AI can help investigate, implement, draft test cases and analyse results. Acceptance and release decisions belong to the designated people.
2. Define the Change and Preserve the Baseline
Agree the problem, affected users, intended outcome and acceptance criteria before implementation. Identify changes to data, configuration, dependencies, permissions and integrations that could affect acceptance or recovery.
Record the exact source revision used for development and the version currently in use. Identify the last known good release and preserve the artifacts and configuration needed to recover it. Retain recovery instructions and references to securely stored backups where applicable. For a first release, define the safe pre-release state and how to return to it, such as disabling the new service and restoring any shared systems it changed.
Develop and investigate in the development environment. Prepare each release candidate with a unique version or build identifier and record its source revision, build inputs, deployment steps, changes and known limitations. Preserve previous candidates and their records. If the artifact, deployment procedure or material configuration changes, record the change and repeat the affected checks on the new candidate.
3. Run Human User Acceptance Testing
Before release, have a named human tester or representative user exercise the candidate in a safe, representative environment. Involve the people who use or operate the affected workflows where practical. Agree what success looks like with them and give them the candidate, setup steps, suitable test data and a place to record their observations.
Cover the scenarios relevant to the change:
- Normal workflows and the original problem the change is meant to solve.
- Installation, upgrade and existing user data where applicable.
- Accessibility, permissions, error handling and common edge cases.
- Regressions in important workflows and recovery from interrupted actions.
Record the candidate identifier, environment, tester, date, expected and observed behaviour, and a Pass, Fail or Pending result for each applicable scenario. Capture the tester’s acceptance decision and any limitations they observed. Keep automated results alongside the human record as supporting evidence. Human UAT stays Pending until a person performs it and records the outcome.
Resolve failures that affect acceptance criteria in development. Issue a new candidate, repeat the affected scenarios and record the new decision. Hold release while required human UAT is pending or an acceptance criterion is unmet.
4. Plan and Rehearse Safe Rollback
Prepare a recovery plan specific to the candidate and the environment before rollout. Cover the parts that can change together, such as application artifacts, configuration, schema, user data, dependencies, background jobs and integrations.
- Trigger and ownership. Define when to stop rollout or start recovery, who makes that decision and how affected people are informed. Use observable signals such as failed health checks, data integrity errors or a broken critical workflow.
- Recovery point. Identify the exact known good artifact, configuration and compatible data state. Confirm that recovery materials are accessible to the responsible people and that backups can be restored.
- Ordered steps. Describe how to stop further impact, restore or switch traffic back, and restart work safely. Where writes can occur during rollout, specify how new records, queued jobs and external side effects will be preserved or reconciled. Define how to avoid replaying actions such as notifications or payments.
- Verification. Specify how to confirm the restored version, service health, key user workflows and data integrity. Record the expected recovery time and any remaining limitations.
Rehearse the applicable recovery steps in a representative environment and record the outcome. For changes with migrations, verify that the earlier version can use the migrated data or demonstrate a safe way to restore or reconcile it. If a direct rollback could lose data or repeat external actions, demonstrate a safer recovery path, such as disabling the change, using a compatible migration or applying a tested corrective release. Hold rollout until the team has demonstrated a viable recovery path and the approver understands its limits.
5. Approve, Release and Monitor
The human release approver confirms that:
- The exact candidate has passed required checks and human UAT.
- The recovery materials are available and the recovery procedure has been rehearsed.
- The release notes identify the version, known limitations, and installation or deployment instructions.
- The recovery owner knows the rollout plan, monitoring period and rollback triggers.
Promote the approved artifact with its verified configuration and record what was deployed, where and when. Use a staged rollout when the project supports it. Monitor the agreed signals and verify key workflows after deployment. If a rollback trigger is met, stop expansion and follow the recovery plan. Record the incident, recovery actions and verification results.
6. Retain Release and Recovery Evidence
Keep the records needed to reproduce the release, explain acceptance and recover safely. The project can use these suggested documents:
| Record | Minimum contents |
|---|---|
CHANGELOG.md |
Candidate and source identifiers, changes, known limitations and validation status |
UAT.md |
Installation or setup, test scenarios, named human participants, results and acceptance decision |
ROLLBACK.md |
Recovery point, triggers, owner, ordered steps, data handling, verification and rehearsal outcome |
| Release record | Approved and deployed artifact, environment, approval, deployment outcome and any recovery actions |
After deployment has been verified and the release is stable, designate it as a known good recovery point. Retain the previous usable point for the project’s recovery window. Preserve significant failures and decisions when they are useful for diagnosis or future work. Apply the project’s retention and access rules to test evidence and backup data, and keep credentials out of release artifacts and shared records.