Skip to content

Commit 42288f4

Browse files
TheNewAutonomyTheNewAutonomy
committed
docs: Phase D release engineering evidence (#264 #276 #277)
Made-with: Cursor
1 parent fcc7589 commit 42288f4

4 files changed

Lines changed: 99 additions & 3 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ These docs are written against the current `catalyst-node-rust` implementation (
77
- **Pre-deploy checklist (executable gates):** [`mainnet-pre-deploy-checklist.md`](./mainnet-pre-deploy-checklist.md)
88
- **Roadmap + GitHub epics (`#260`–`#284`):** [`mainnet-roadmap.md`](./mainnet-roadmap.md)
99
- **#275 / C2 reset–recovery evidence (retrospective template):** [`evidence/track275-reset-recovery-evidence.md`](./evidence/track275-reset-recovery-evidence.md)
10+
- **Phase D / #264–#277 release + upgrade evidence:** [`evidence/phase-d-release-engineering-evidence.md`](./evidence/phase-d-release-engineering-evidence.md)
1011

1112
## Guides
1213

‎docs/evidence/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,11 @@ Reset / recovery / backfill sign-off for GitHub issue **#275** (checklist **C2**
2121
- **Purpose:** retrospective documentation when resets were performed but not logged per event.
2222
- **Location:** [`track275-reset-recovery-evidence.md`](./track275-reset-recovery-evidence.md)
2323
- **Action:** fill in, commit, then close **#275** with the doc link.
24+
25+
---
26+
27+
## `phase-d-release-engineering-evidence.md`
28+
29+
Release process, provenance (**#264**, **#276**), and upgrade/rollback matrix (**#277**) for checklist **Phase D**.
30+
31+
- **Location:** [`phase-d-release-engineering-evidence.md`](./phase-d-release-engineering-evidence.md)

‎docs/evidence/phase-d-release-engineering-evidence.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Phase D — Release engineering + upgrade safety (issues **#264**, **#276**, **#277**)
2+
3+
This document supports closing checklist **Phase D** in [`mainnet-pre-deploy-checklist.md`](../mainnet-pre-deploy-checklist.md).
4+
5+
---
6+
7+
## D1 — Release build process + provenance (**#264**, **#276**)
8+
9+
### What is already defined in this repository
10+
11+
| Topic | Where / what |
12+
|--------|----------------|
13+
| **Release steps** | [`release-process.md`](../release-process.md) — tags `v*.*.*`, GitHub Release, artifact names |
14+
| **CI gate before ship** | `.github/workflows/ci.yml` — `cargo test --workspace --locked` |
15+
| **Release artifacts** | `.github/workflows/release.yml` — `cargo build -p catalyst-cli --release --locked`, tarball `catalyst-cli-<tag>-x86_64-unknown-linux-gnu.tar.gz`, **SHA256** sidecar |
16+
| **Checksums** | Per-binary `SHA256SUMS` inside tarball + `.sha256` for the `.tar.gz` (see workflow) |
17+
| **Wire compatibility** | [`release-process.md`](../release-process.md) — golden vectors in `crates/catalyst-core/tests/wire_vectors.rs` |
18+
| **Version reporting** | `catalyst_version` RPC / `catalyst-cli --version` (per `release-process.md`) |
19+
20+
### Reproducible builds + SBOM (**#276**)
21+
22+
- **Bit-for-bit reproducible** Linux binaries are **not** asserted by automation in this repo today.
23+
- **Provenance** that *is* available for operators:
24+
- **Git tag** + **commit** on `main`
25+
- **GitHub Actions** run for the tag (`release.yml`)
26+
- **SHA256** of the published tarball (verify after download)
27+
- **`--locked`** builds in CI/release for dependency determinism from `Cargo.lock`
28+
29+
_(Optional — add your org’s policy: e.g. “SBOM deferred to post-mainnet” or link to an external SBOM artifact.)_
30+
31+
### D1 sign-off (fill in)
32+
33+
- [ ] We accept the **documented release process** ([`release-process.md`](../release-process.md)) + **checksums + locked builds** as sufficient provenance for mainnet v1.
34+
- [ ] **Release tag used for mainnet binaries:** `v_____` **Commit:** `__________`
35+
- [ ] **Notes (optional):** …
36+
37+
| Name | Date |
38+
|------|------|
39+
| | |
40+
41+
---
42+
43+
## D2 — Upgrade matrix + rollback (**#277**)
44+
45+
### Documented rollback path (code + docs)
46+
47+
- **Before upgrade:** `catalyst-cli db-backup` — [`node-operator-guide.md`](../node-operator-guide.md) § *Upgrades, backups, and rollback safety*
48+
- **If upgrade fails:** `catalyst-cli db-restore` from the backup directory
49+
- **Chain identity:** do not change `chain_id` / `network_id` / genesis for a “running” network except as a **new chain** — [`protocol-params.md`](../protocol-params.md)
50+
- **On-disk marker:** `storage:version` helps detect mismatches across upgrades (see node-operator guide)
51+
52+
### Suggested upgrade matrix (fill in what you actually tested)
53+
54+
| Scenario | Binary / version | Data dir | Tested? | Result / notes |
55+
|----------|------------------|----------|---------|----------------|
56+
| Same tag, restart only | … | … | ☐ | |
57+
| New patch release, same `Cargo.lock` line / compatible | … | … | ☐ | |
58+
| After `db-backup`, replace binary, start | … | … | ☐ | |
59+
| Rollback: `db-restore` + previous binary | … | … | ☐ | |
60+
61+
**Local dev example (optional):** stop testnet → backup `testnet/node1/data` → upgrade binary → `testnet-up` → smoke `catalyst_status` / head advancing; rollback = restore backup + old binary.
62+
63+
### D2 sign-off (fill in)
64+
65+
- [ ] **Coordinated upgrade** assumption documented: operators agree on **tag**, **backup window**, and **rollback** using **db-backup / db-restore**.
66+
- [ ] **Residual:** cross-version P2P / consensus incompatibility is handled by **release notes** + **not** mixing incompatible majors on one network.
67+
68+
| Name | Date |
69+
|------|------|
70+
| | |
71+
72+
---
73+
74+
## Close on GitHub
75+
76+
Comment on **#264**, **#276**, **#277** (or umbrella **#260**):
77+
*“Phase D evidence: `docs/evidence/phase-d-release-engineering-evidence.md` @ \<commit\>”*
78+
79+
---
80+
81+
## Related
82+
83+
- [`release-process.md`](../release-process.md)
84+
- [`node-operator-guide.md`](../node-operator-guide.md) — upgrades, backups, rollback
85+
- [`mainnet-roadmap.md`](../mainnet-roadmap.md) — epics **#264**, **#276**, **#277**

‎docs/mainnet-pre-deploy-checklist.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ Use this document to **drive execution** before cutting a public mainnet. It con
4747
| C1 | WAN soak / load / chaos gate meets thresholds (or failures have follow-up issues). | [`wan-soak-load-chaos-gate.md`](./wan-soak-load-chaos-gate.md) | `#263`, `#274` |
4848
| C2 | Reset / recovery / backfill reliability acceptable for operators. | [`evidence/track275-reset-recovery-evidence.md`](./evidence/track275-reset-recovery-evidence.md) (retrospective OK) | `#275` |
4949

50-
**Sign-off:** Name / date: _______________
50+
**Sign-off:** Name / date: TheNewAutonomy 22nd March 2026
5151

5252
**Note:** If you reset testnets many times but did not log each run, complete **C2** by filling in the retrospective sections in `evidence/track275-reset-recovery-evidence.md` and linking it when closing **#275**.
5353

@@ -57,11 +57,13 @@ Use this document to **drive execution** before cutting a public mainnet. It con
5757

5858
| # | Item | Evidence / doc | GitHub |
5959
|---|------|----------------|--------|
60-
| D1 | Release build process documented; binaries reproducible or provenance captured as required. | [`release-process.md`](./release-process.md) | `#264`, `#276` |
61-
| D2 | Upgrade matrix + rollback path tested (coordinated upgrade assumptions documented). | Operator notes | `#277` |
60+
| D1 | Release build process documented; binaries reproducible or provenance captured as required. | [`release-process.md`](./release-process.md), [`evidence/phase-d-release-engineering-evidence.md`](./evidence/phase-d-release-engineering-evidence.md) | `#264`, `#276` |
61+
| D2 | Upgrade matrix + rollback path tested (coordinated upgrade assumptions documented). | [`evidence/phase-d-release-engineering-evidence.md`](./evidence/phase-d-release-engineering-evidence.md) (matrix + [`node-operator-guide.md`](./node-operator-guide.md)) | `#277` |
6262

6363
**Sign-off:** Name / date: _______________
6464

65+
**Note:** Full bit-reproducible builds / SBOM may be optional for v1; this repo documents **tag + CI + `--locked` + SHA256 artifacts** — see the Phase D evidence file. Fill D1/D2 sign-offs and the upgrade matrix there to close the phase.
66+
6567
---
6668

6769
## Phase E — Operations

0 commit comments

Comments
 (0)