Release Playbook

Purpose

Define the operational release flow from freeze to tag for DSAMbayes v1.2.2, including rollback and hotfix handling.

Audience and roles

  • Release owner (cshaw): drives the checklist, evidence pack, and final go or no-go call.
  • Maintainers: execute gates, review failures, and approve release PRs.
  • Reviewers: verify evidence and sign off risk acceptance.

Release inputs

Release work starts only when these inputs are ready:

  1. CHANGELOG.md reflects the release candidate contents.
  2. DESCRIPTION has the intended release version.
  3. Required docs pages for quality and runner workflows are in place.
  4. Candidate commit hash is identified on main or master.

Step-by-step flow

1. Freeze the release candidate

Actions:

  1. Announce code freeze window and candidate commit hash.
  2. Stop merging non-release changes until gate outcome is known.
  3. Confirm release scope is documentation and refactor changes planned for v1.2.2.

Expected outcome: one stable candidate commit is selected for gate execution.

2. Prepare local release environment

Actions:

  1. Create repo-local paths and environment variables.
  2. Install local package into .Rlib.

Commands:

# Navigate to your local DSAMbayes checkout
cd /path/to/DSAMbayes
mkdir -p .Rlib .cache
export R_LIBS_USER="$PWD/.Rlib"
export XDG_CACHE_HOME="$PWD/.cache"
R_LIBS_USER="$PWD/.Rlib" R -q -e 'install.packages(".", repos = NULL, type = "source")'

Expected outcome: release checks run in a reproducible local environment.

3. Run mandatory quality gates

Execute gates QG-1 to QG-7 from Quality Gates in order.

Commands:

R_LIBS_USER="$PWD/.Rlib" Rscript scripts/check.R --lint
R_LIBS_USER="$PWD/.Rlib" Rscript scripts/check.R --style
R_LIBS_USER="$PWD/.Rlib" R -q -e 'testthat::test_dir("tests/testthat")'
R_LIBS_USER="$PWD/.Rlib" R -q -e 'rcmdcheck::rcmdcheck(args = c("--no-manual","--compact-vignettes=gs+qpdf"))'
R_LIBS_USER="$PWD/.Rlib" Rscript scripts/dsambayes.R validate --config config/blm_synthetic_mcmc.yaml --run-dir results/quality_gate_validate
R_LIBS_USER="$PWD/.Rlib" Rscript scripts/dsambayes.R run --config config/blm_synthetic_mcmc.yaml --run-dir results/quality_gate_run
R_LIBS_USER="$PWD/.Rlib" Rscript -e 'pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)'

Expected outcome: all mandatory gates pass with exit code 0, with no unresolved WARNING or ERROR.

4. Confirm CI workflow status

Actions:

  1. Confirm .github/workflows/R-CMD-check.yaml is green for the candidate commit.
  2. Confirm .github/workflows/pkgdown.yaml build step is green for the candidate commit.
  3. For non-PR release flow, confirm pkgdown deploy step eligibility and permissions.

Expected outcome: CI evidence aligns with local gate outcomes.

5. Finalise release metadata

Actions:

  1. Re-check DESCRIPTION version and CHANGELOG.md top section.
  2. Ensure release notes correspond to the candidate commit only.
  3. Commit final metadata edits if needed.

Expected outcome: version metadata and release notes are internally consistent.

6. Build release evidence and sign-off record

Actions:

  1. Assemble logs and artefacts defined in Release Evidence Pack.
  2. Record gate outcomes and decision in Release Sign-off Template.
  3. Capture any accepted NOTE rationale from rcmdcheck.

Expected outcome: auditable evidence bundle is complete and signed.

7. Create and push release tag

Create an annotated tag for the approved version and push it.

Commands:

git tag -a v1.2.2 -m "DSAMbayes v1.2.2"
git push origin v1.2.2

Expected outcome: release tag v1.2.2 exists on remote and points to the signed-off commit.

8. Publish release and verify post-release state

Actions:

  1. Publish the GitHub release from tag v1.2.2.
  2. Confirm pkgdown.yaml runs on release published event.
  3. Confirm deployed docs are up to date.

Expected outcome: release record and documentation deployment are complete.

Go or no-go rules

  1. NO-GO if any mandatory quality gate fails.
  2. NO-GO if release evidence or sign-off template is incomplete.
  3. NO-GO if version metadata and changelog are inconsistent.
  4. GO only when all gates pass and sign-off is recorded.

Rollback procedure

Use this procedure if a release must be withdrawn.

Case A: tag created, release not published

Actions:

  1. Delete the local tag.
  2. Delete the remote tag.
  3. Open a corrective PR and restart gate execution.

Commands:

git tag -d v1.2.2
git push origin :refs/tags/v1.2.2

Expected outcome: withdrawn tag is removed and cannot trigger downstream release steps.

Case B: release published

Actions:

  1. Mark the published release as superseded with a clear incident note.
  2. Do not rewrite history on main or master.
  3. Cut a hotfix release using the hotfix path below.

Expected outcome: users are directed to a corrected patch release.

Hotfix path

Use this path for a defect found after publication.

  1. Branch from the released tag.
git checkout -b hotfix/v1.2.3 v1.2.2
  1. Apply the minimal fix and update release metadata.

Actions:

  • bump DESCRIPTION version to 1.2.1
  • add a DSAMbayes 1.2.1 section at top of CHANGELOG.md
  1. Re-run mandatory gates (QG-1 to QG-7).
  2. Obtain sign-off with explicit incident reference.
  3. Tag and publish v1.2.1.

Commands:

git tag -a v1.2.1 -m "DSAMbayes v1.2.1 hotfix"
git push origin v1.2.1

Expected outcome: defect is remediated in a new immutable patch release.