Quality Gates

Purpose

Define the canonical release-quality gates for DSAMbayes v1.2.2, including commands, pass/fail criteria, and evidence requirements.

Audience

• Maintainers preparing a release candidate
• Reviewers signing off release readiness
• Engineers running local pre-merge quality checks

Gate Matrix

Gate Definitions

QG-1 Lint

Command:

R_LIBS_USER="$PWD/.Rlib" Rscript scripts/check.R --lint

Fail conditions:

• Non-zero exit code
• Any lint issue reported
• Any SKIP: output

QG-2 Style

Command:

R_LIBS_USER="$PWD/.Rlib" Rscript scripts/check.R --style

Fail conditions:

• Non-zero exit code
• Any file reported as requiring reformat
• Any SKIP: output

QG-3 Unit Tests

Command:

R_LIBS_USER="$PWD/.Rlib" R -q -e 'testthat::test_dir("tests/testthat")'

Fail conditions:

• Non-zero exit code
• Any test failure or error

QG-4 Package Check

Command:

R_LIBS_USER="$PWD/.Rlib" R -q -e 'rcmdcheck::rcmdcheck(args = c("--no-manual","--compact-vignettes=gs+qpdf"))'

Fail conditions:

• Any ERROR
• Any WARNING for release sign-off

Escalation condition:

• Any NOTE must be reviewed and explicitly accepted with rationale.

QG-5 Runner Smoke: Validate

Command:

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate \
    --config config/blm_synthetic_mcmc.yaml \
    --run-dir results/quality_gate_validate

Fail conditions:

• Non-zero exit code
• Missing results/quality_gate_validate/00_run_metadata/config.resolved.yaml

QG-6 Runner Smoke: Run

Command:

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run \
    --config config/blm_synthetic_mcmc.yaml \
    --run-dir results/quality_gate_run

Fail conditions:

• Non-zero exit code
• Missing results/quality_gate_run/00_run_metadata/config.resolved.yaml
• Missing results/quality_gate_run/20_model_fit/model.rds
• Missing results/quality_gate_run/30_post_run/posterior_summary.csv
• Missing results/quality_gate_run/40_diagnostics/diagnostics_report.csv

QG-7 Docs Build Check

Command:

R_LIBS_USER="$PWD/.Rlib" \
  Rscript -e 'pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)'

Fail conditions:

• Non-zero exit code
• pkgdown build aborts before site generation

Command Reference

Recommended environment setup before running gates:

# 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"

Optional consolidated local gate (does not replace all release gates):

R_LIBS_USER="$PWD/.Rlib" Rscript scripts/check.R --all

scripts/check.R --all covers lint, style, tests, and coverage. It does not run rcmdcheck, runner smoke checks, or pkgdown build.

Evidence Requirements

Minimum evidence bundle per release candidate:

1. Full terminal output and exit code for each gate QG-1 to QG-7.
2. Runner smoke artefacts under results/quality_gate_validate/.
3. Runner smoke artefacts under results/quality_gate_run/.
4. rcmdcheck summary with explicit handling of NOTEs.
5. Confirmation that no gate result is SKIP.

Evidence review should reference:

• Release Readiness Checklist
• Release Evidence Pack
• Release Sign-off Template

Failure and Escalation Rules

1. Any gate failure blocks release tagging.
2. Do not proceed to sign-off with unresolved ERROR or WARNING.
3. NOTEs require written rationale and reviewer acceptance.
4. If a gate fails due to environment setup, fix the environment and re-run the full affected gate.
5. If a gate fails due to product code, raise a remediation change and re-run from QG-1.

Sign-off Criteria

Release sign-off requires all of the following:

1. QG-1 to QG-7 passed.
2. No SKIP outcomes across mandatory gates.
3. Evidence bundle completed and reviewed.
4. Final decision recorded in sign-off-template.md.

Testing and Validation

Purpose

Define the canonical testing and validation workflow for DSAMbayes v1.2.2, from local pre-merge checks through release-quality gates.

Audience

• Engineers running local checks before merge
• Maintainers preparing release candidates
• Reviewers validating release evidence

Validation layers

Environment setup

Run all commands from repository root:

# 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"

Expected outcome: checks run in a repo-scoped environment with reproducible library and cache paths.

Local validation workflows

Developer fast path (pre-merge)

Run the consolidated local gate:

R_LIBS_USER="$PWD/.Rlib" Rscript scripts/check.R --all

Expected outcome: lint, style, tests, and coverage complete successfully.

Implementation note: scripts/check.R --all is a convenience gate. It does not replace rcmdcheck, runner smoke tests, or docs build.

Release-candidate full path

Run mandatory gates in this exact order:

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 gates complete with exit code 0, with no unresolved release blockers.

Runner smoke-test expectations

Minimum release smoke expectations:

1. validate command succeeds and writes metadata artefacts.
2. run command succeeds and writes model, posterior summary, and diagnostics artefacts.
3. Required runner artefact paths exist under results/quality_gate_validate/ and results/quality_gate_run/.

For matrix and exact artefact paths, use Runner Smoke Tests.

CI validation expectations

Candidate commit should have:

1. Passing .github/workflows/R-CMD-check.yaml.
2. Passing .github/workflows/pkgdown.yaml build.
3. Deploy-step eligibility confirmed for non-PR release flow.

For workflow semantics and expected proof, use CI Workflows.

Evidence capture requirements

Before sign-off, capture:

1. Full command logs and exit codes for all mandatory gates.
2. Runner smoke artefacts from validate and run directories.
3. CI run URLs and statuses for both workflows.
4. Candidate commit hash and top changelog section.

Use Release Evidence Pack as the authoritative bundle contract.

Failure handling

1. Any gate failure is a release blocker until resolved.
2. Re-run the full failed gate after remediation.
3. If rcmdcheck emits NOTE, record reviewer rationale explicitly.
4. If runner artefacts are missing, inspect resolved config and outputs.* flags.

Related pages

• Quality Gates
• Runner Smoke Tests
• CI Workflows
• Release Evidence Pack
• Release Readiness Checklist
• Release Sign-off Template

Runner Smoke Tests

Purpose

Define the minimal reproducible smoke-test matrix for the YAML runner validate and run commands, including exact commands and expected artefacts.

Audience

• Maintainers preparing release evidence
• Engineers triaging runner regressions
• Reviewers confirming gate QG-5 and QG-6

Test scope

This smoke suite is intentionally small. It proves:

• CLI argument handling for validate and run
• Config resolution and runner pre-flight path
• End-to-end artefact writing for one full run

This smoke suite does not replace unit tests or full package checks.

Preconditions

Run from repository root:

# 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"

Expected outcome: commands resolve local package/library paths and use repo-scoped Stan cache.

Install DSAMbayes locally if needed:

R_LIBS_USER="$PWD/.Rlib" R -q -e 'install.packages(".", repos = NULL, type = "source")'

Expected outcome: library(DSAMbayes) succeeds in the same shell session.

Smoke-test matrix

Canonical commands

SMK-VAL-01

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate \
    --config config/blm_synthetic_mcmc.yaml \
    --run-dir results/smoke_validate_blm

Expected outcome: validation completes without Stan fitting and prints Status: ok.

SMK-VAL-02

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate \
    --config config/hierarchical_re_synthetic_mcmc.yaml \
    --run-dir results/smoke_validate_hier_re

Expected outcome: validation completes for hierarchical RE config and prints Status: ok.

SMK-VAL-03

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate \
    --config config/pooled_synthetic_mcmc.yaml \
    --run-dir results/smoke_validate_pooled

Expected outcome: validation completes for pooled config and prints Status: ok.

SMK-RUN-01

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run \
    --config config/blm_synthetic_mcmc.yaml \
    --run-dir results/smoke_run_blm

Expected outcome: full pipeline completes and prints Run complete with a resolved run directory.

Expected artefacts

Validate artefacts (SMK-VAL-01 to SMK-VAL-03)

For each validate run directory, these files are required:

• 00_run_metadata/config.original.yaml
• 00_run_metadata/config.resolved.yaml
• 00_run_metadata/session_info.txt

Failure rule: missing any required file is a smoke-test failure.

Run artefacts (SMK-RUN-01)

Required core artefacts:

• 00_run_metadata/config.resolved.yaml
• 20_model_fit/model.rds
• 30_post_run/posterior_summary.csv
• 40_diagnostics/diagnostics_report.csv

Recommended additional checks for stronger confidence:

• 30_post_run/fitted.csv
• 30_post_run/observed.csv
• 40_diagnostics/diagnostics_summary.txt

Failure rule: missing any required core artefact is a smoke-test failure.

Verification helper commands

Check validate artefacts quickly:

for d in results/smoke_validate_blm results/smoke_validate_hier_re results/smoke_validate_pooled; do
  test -f "$d/00_run_metadata/config.original.yaml" || echo "MISSING: $d config.original.yaml"
  test -f "$d/00_run_metadata/config.resolved.yaml" || echo "MISSING: $d config.resolved.yaml"
  test -f "$d/00_run_metadata/session_info.txt" || echo "MISSING: $d session_info.txt"
done

Expected outcome: no MISSING: lines.

Check core run artefacts quickly:

d="results/smoke_run_blm"
test -f "$d/00_run_metadata/config.resolved.yaml" || echo "MISSING: config.resolved.yaml"
test -f "$d/20_model_fit/model.rds" || echo "MISSING: model.rds"
test -f "$d/30_post_run/posterior_summary.csv" || echo "MISSING: posterior_summary.csv"
test -f "$d/40_diagnostics/diagnostics_report.csv" || echo "MISSING: diagnostics_report.csv"

Expected outcome: no MISSING: lines.

Failure triage

1. If validate fails, run the same command again with a clean run directory path and inspect CLI error output.
2. If run fails before fitting, inspect 00_run_metadata/config.resolved.yaml to confirm resolved values.
3. If run fails during fitting, verify local Stan toolchain and cache path from Install and Setup.
4. If artefacts are missing after success exit code, inspect outputs.* flags in the resolved config.

Evidence capture

For release evidence, capture:

1. Full terminal logs and exit codes for SMK-VAL-01 to SMK-RUN-01.
2. Directory listings for each smoke run directory.
3. The required artefacts listed above.

Store and review evidence with:

• Quality Gates
• Release Evidence Pack
• Release Sign-off Template

CI Workflows

Purpose

Define what the repository CI workflows execute, what each workflow is expected to prove, and where each workflow fits in release evidence.

Audience

• Maintainers who triage CI failures and approve merges
• Reviewers validating release evidence
• Engineers who need to map local checks to CI outcomes

Workflow inventory

R-CMD-check.yaml

Trigger conditions

R-CMD-check.yaml runs on:

• push to main or master
• pull_request targeting main or master

Job contract

The workflow defines one matrix job named R-CMD-check with fail-fast: false across:

• macos-latest with R release
• windows-latest with R release
• ubuntu-latest with R devel
• ubuntu-latest with R release
• ubuntu-latest with R oldrel-1

Each matrix cell executes:

1. Repository checkout (actions/checkout@v4)
2. Pandoc setup (r-lib/actions/setup-pandoc@v2)
3. R setup (r-lib/actions/setup-r@v2)
4. Dependency resolution for checks (r-lib/actions/setup-r-dependencies@v2, needs: check, extra-packages: any::rcmdcheck)
5. Package check (r-lib/actions/check-r-package@v2) with:
   • build_args: c("--no-manual","--compact-vignettes=gs+qpdf")
   • upload-snapshots: true

What this job is expected to prove

• The package can be installed and checked on the supported CI matrix.
• R CMD check passes without check-level failures on each matrix cell.
• The package dependency graph in DESCRIPTION resolves in CI for each matrix cell.

What this job does not prove

• It does not run scripts/check.R --lint or scripts/check.R --style.
• It does not run runner smoke commands (scripts/dsambayes.R validate or run).
• It does not build or deploy pkgdown documentation.

pkgdown.yaml

Trigger conditions

pkgdown.yaml runs on:

• push to main or master
• pull_request targeting main or master
• release events where type is published
• Manual dispatch (workflow_dispatch)

Job contract

The workflow defines a single pkgdown job on ubuntu-latest with:

• Concurrency group pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
• Workflow-level permissions: read-all
• Job-level permissions: contents: write

The job executes:

1. Repository checkout (actions/checkout@v4)
2. Pandoc setup (r-lib/actions/setup-pandoc@v2)
3. R setup (r-lib/actions/setup-r@v2, use-public-rspm: true)
4. Website dependencies (r-lib/actions/setup-r-dependencies@v2, needs: website, extra-packages: any::pkgdown, local::.)
5. Site build (pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE))
6. Deploy step (JamesIves/github-pages-deploy-action@v4.5.0) only when event is not pull_request

What this job is expected to prove

• The pkgdown site can be generated from the current repository state.
• Package documentation inputs required by pkgdown are valid enough to build the site.
• On non-PR events, generated site output under docs/ can be pushed to gh-pages.

What this job does not prove

• It does not replace R CMD check as a package correctness gate.
• It does not execute full runner smoke tests.
• It does not provide release sign-off on its own.

Required secrets and permissions

• Both workflows set GITHUB_PAT from secrets.GH_PAT.
• R-CMD-check.yaml runs with read-only repository permissions (read-all).
• pkgdown.yaml requires contents: write in the pkgdown job to push to gh-pages.

If GH_PAT is absent, steps that require authenticated GitHub API access can hit stricter rate limits.

Expected logs and artefacts

R-CMD-check.yaml

Expected evidence in the GitHub Actions run:

• One job result per matrix cell
• check-r-package logs for each cell
• Clear pass or fail state per OS/R pair

pkgdown.yaml

Expected evidence in the GitHub Actions run:

• Build site log showing pkgdown generation status
• Deploy to GitHub pages log for non-PR events
• No deploy step execution for PR events

Failure handling

1. Treat any red CI job as a merge blocker until resolved or explicitly waived.
2. Reproduce failures locally with the nearest equivalent command:
   • R CMD check failure: run the rcmdcheck command from Quality Gates.
   • pkgdown build failure: run the pkgdown command from Quality Gates.
3. If failure is environment-specific (for example one matrix OS), capture that scope in the PR and link the failing job URL.
4. Re-run failed jobs only after a code or environment change that addresses the root cause.

Relationship to release gates

• R-CMD-check.yaml provides CI evidence for gate QG-4 in Quality Gates.
• pkgdown.yaml provides CI evidence for gate QG-7 in Quality Gates.
• Release sign-off still requires the full gate set and evidence bundle.

Release Evidence Pack

Purpose

Define the exact evidence bundle required before release sign-off for DSAMbayes v1.2.2.

Audience

• Release owner preparing sign-off materials
• Reviewers validating release readiness
• Maintainers reproducing release gate outcomes

Evidence root and naming

Use one evidence root per candidate release.

Recommended path:

release_evidence/v1.2.2/<YYYYMMDD>_<short_sha>/

Example:

release_evidence/v1.2.2/20260228_0d68378/

Expected outcome: all sign-off evidence is stored in one deterministic location.

Mandatory evidence bundle

All items below are mandatory.

Exact required artefact paths

EVD-10 validate artefacts (QG-5)

Copy these paths from the run directory:

• results/quality_gate_validate/00_run_metadata/config.original.yaml
• results/quality_gate_validate/00_run_metadata/config.resolved.yaml
• results/quality_gate_validate/00_run_metadata/session_info.txt

EVD-11 run artefacts (QG-6)

Copy these paths from the run directory:

• results/quality_gate_run/00_run_metadata/config.resolved.yaml
• results/quality_gate_run/20_model_fit/model.rds
• results/quality_gate_run/30_post_run/posterior_summary.csv
• results/quality_gate_run/40_diagnostics/diagnostics_report.csv

Collection commands

Create evidence structure:

mkdir -p release_evidence/v1.2.2/$(date +%Y%m%d)_$(git rev-parse --short HEAD)/{00_release_identity,10_quality_gates,20_runner_artifacts,30_ci,40_signoff}

Expected outcome: canonical evidence folders exist.

Capture release identity and changelog proof:

EROOT="release_evidence/v1.2.2/$(date +%Y%m%d)_$(git rev-parse --short HEAD)"
{
  echo "candidate_commit=$(git rev-parse HEAD)"
  echo "candidate_branch=$(git rev-parse --abbrev-ref HEAD)"
  echo "target_tag=v1.2.2"
  echo "package_version=$(awk -F': ' '/^Version:/{print $2}' DESCRIPTION)"
} > "$EROOT/00_release_identity/release_identity.txt"

sed -n '1,120p' CHANGELOG.md > "$EROOT/00_release_identity/changelog_top.md"

Expected outcome: release_identity.txt and changelog_top.md are populated.

Capture gate logs and exit codes:

EROOT="release_evidence/v1.2.2/$(date +%Y%m%d)_$(git rev-parse --short HEAD)"

R_LIBS_USER="$PWD/.Rlib" Rscript scripts/check.R --lint > "$EROOT/10_quality_gates/qg1_lint.log" 2>&1; echo $? > "$EROOT/10_quality_gates/qg1_lint.exit"
R_LIBS_USER="$PWD/.Rlib" Rscript scripts/check.R --style > "$EROOT/10_quality_gates/qg2_style.log" 2>&1; echo $? > "$EROOT/10_quality_gates/qg2_style.exit"
R_LIBS_USER="$PWD/.Rlib" R -q -e 'testthat::test_dir("tests/testthat")' > "$EROOT/10_quality_gates/qg3_tests.log" 2>&1; echo $? > "$EROOT/10_quality_gates/qg3_tests.exit"
R_LIBS_USER="$PWD/.Rlib" R -q -e 'rcmdcheck::rcmdcheck(args = c("--no-manual","--compact-vignettes=gs+qpdf"))' > "$EROOT/10_quality_gates/qg4_rcmdcheck.log" 2>&1; echo $? > "$EROOT/10_quality_gates/qg4_rcmdcheck.exit"
R_LIBS_USER="$PWD/.Rlib" Rscript scripts/dsambayes.R validate --config config/blm_synthetic_mcmc.yaml --run-dir results/quality_gate_validate > "$EROOT/10_quality_gates/qg5_validate.log" 2>&1; echo $? > "$EROOT/10_quality_gates/qg5_validate.exit"
R_LIBS_USER="$PWD/.Rlib" Rscript scripts/dsambayes.R run --config config/blm_synthetic_mcmc.yaml --run-dir results/quality_gate_run > "$EROOT/10_quality_gates/qg6_run.log" 2>&1; echo $? > "$EROOT/10_quality_gates/qg6_run.exit"
R_LIBS_USER="$PWD/.Rlib" Rscript -e 'pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)' > "$EROOT/10_quality_gates/qg7_pkgdown.log" 2>&1; echo $? > "$EROOT/10_quality_gates/qg7_pkgdown.exit"

Expected outcome: seven gate logs and seven exit-code files are present.

Copy runner artefacts:

EROOT="release_evidence/v1.2.2/$(date +%Y%m%d)_$(git rev-parse --short HEAD)"
mkdir -p "$EROOT/20_runner_artifacts"
cp -R results/quality_gate_validate "$EROOT/20_runner_artifacts/"
cp -R results/quality_gate_run "$EROOT/20_runner_artifacts/"

Expected outcome: runner artefacts are captured under evidence storage.

Evidence review checklist

Before sign-off, reviewers must confirm all items below:

1. release_identity.txt commit hash matches the commit being tagged.
2. package_version in release_identity.txt matches the intended release (1.2.0).
3. changelog_top.md includes a DSAMbayes 1.2.0 section aligned with candidate changes.
4. Every qg*.exit file contains 0.
5. Required QG-5 and QG-6 artefact paths exist.
6. ci_run_summary.md records CI run links and final statuses for both workflows.
7. Completed sign-off record exists at 40_signoff/sign_off_record.md.

CI summary file contract (EVD-12)

30_ci/ci_run_summary.md must contain:

• Candidate commit hash
• URL and status for .github/workflows/R-CMD-check.yaml
• URL and status for .github/workflows/pkgdown.yaml
• Reviewer name and review timestamp in UTC

Submission and retention

1. Submit the evidence root path in the release PR and in the sign-off record.
2. Do not delete evidence for approved releases.
3. For rejected releases, retain evidence and mark decision as NO-GO in sign-off.

Related pages

• Quality Gates
• Runner Smoke Tests
• CI Workflows
• Release Playbook
• Release Readiness Checklist
• Testing and Validation
• Release Sign-off Template

Release Readiness Checklist

Purpose

Provide the mandatory go or no-go checklist before creating a DSAMbayes release tag.

How to use this checklist

1. Complete this checklist after running all release-quality gates.
2. Record evidence paths for each item.
3. If any mandatory item fails, decision is NO-GO.
4. Copy final decision details into Release Sign-off Template.

Mandatory checklist

Required runner artefact checks

Validate artefacts that must exist:

1. 20_runner_artifacts/quality_gate_validate/00_run_metadata/config.original.yaml
2. 20_runner_artifacts/quality_gate_validate/00_run_metadata/config.resolved.yaml
3. 20_runner_artifacts/quality_gate_validate/00_run_metadata/session_info.txt

Run artefacts that must exist:

1. 20_runner_artifacts/quality_gate_run/00_run_metadata/config.resolved.yaml
2. 20_runner_artifacts/quality_gate_run/20_model_fit/model.rds
3. 20_runner_artifacts/quality_gate_run/30_post_run/posterior_summary.csv
4. 20_runner_artifacts/quality_gate_run/40_diagnostics/diagnostics_report.csv

Decision rules

1. GO only if every checklist item RL-01 to RL-15 passes.
2. NO-GO if any mandatory item fails or evidence is incomplete.
3. HOLD if no hard failure exists but final approval is pending.
4. Tag creation is allowed only after GO decision is recorded.

Completion record template

Use this section when running the checklist.

Audit continuity reference

For programme-level historical traceability, also review:

• refactoring_plan/release_readiness_checklist_v1.2.md

This page is the operational checklist for current release execution.

Related pages

• Testing and Validation
• Quality Gates
• Runner Smoke Tests
• CI Workflows
• Release Evidence Pack
• Release Playbook
• Release Sign-off Template

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

2. 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

3. Re-run mandatory gates (QG-1 to QG-7).
4. Obtain sign-off with explicit incident reference.
5. 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.

Traceability links

• Quality Gates
• CI Workflows
• Runner Smoke Tests
• Release Evidence Pack
• Release Readiness Checklist
• Release Sign-off Template

Sign-off Template

Purpose

Provide the final approval record for a DSAMbayes release candidate after all mandatory evidence has been reviewed.

Instructions

1. Copy this template into the candidate evidence bundle as 40_signoff/sign_off_record.md.
2. Complete every field.
3. Use GO, NO-GO, or HOLD for the decision.
4. If any exception is accepted, record explicit rationale and owner.

Release identification

Decision summary

Decision rationale:

<fill>

Quality gate outcomes

Mandatory artefact checks

CI confirmation

Exceptions and risk acceptance

Record every exception. If there are none, write none.

Required follow-up actions

Record actions that must happen after release decision.

Final approval signatures

Final decision statement

<Release vX.Y.Z is approved for tagging and publication.>

or

<Release vX.Y.Z is not approved. See exceptions and actions.>

Related pages

• Quality Gates
• Release Evidence Pack
• Release Playbook
• Release Readiness Checklist
• Testing and Validation