Skip to content

docs(runbooks): development, release, CI-triage and upstream-sync runbooks (2/5) - #16

Open
sqr00t wants to merge 1 commit into
docs/adr-recordsfrom
docs/runbooks
Open

docs(runbooks): development, release, CI-triage and upstream-sync runbooks (2/5)#16
sqr00t wants to merge 1 commit into
docs/adr-recordsfrom
docs/runbooks

Conversation

@sqr00t

@sqr00t sqr00t commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Closes #12.

Adds four operational runbooks under docs/runbooks/, plus an index. No code changes —
documentation only. Five files, 846 added lines, nothing deleted.

What is here

Runbook Lines Covers
README.md 17 Index: which runbook to reach for, and the unverified convention
local-development.md 185 Fresh clone to green tests, per-OS toolchain, the stale-extension trap, the tox matrix
release-and-publish.md 190 Pre-release checklist, tagging, the publish workflow, verifying the upload, rollback
ci-triage.md 230 A red check per workflow and job, with the fix for each
upstream-sync.md 224 Diffing against upstream bw, what may diverge, re-verifying goldens

What to check when reviewing

Follow one, do not read it. These are procedures, and the only real test is whether they work
when executed cold. local-development.md on a machine without the toolchain already installed is
the highest-value check.

Two specific things worth a second opinion:

  • The stale-extension trap in local-development.md (§5). Editing C++ and re-running pytest
    without rebuilding silently tests the previously compiled _core — the change appears to do
    nothing. The runbook's stated fix should be the one you would actually use.
  • The decision procedure in ci-triage.md for a failing regression test: is this a real model
    change or platform libm drift? That branch determines whether someone re-baselines a golden value
    or hunts a bug, so getting it wrong is expensive in both directions.

ci-triage.md §2 also documents the Linux-versus-macOS divergence class (GCC/libstdc++ against
libc++) that produced #7 and bf87e07, because it reads as CI flakiness the first time you hit it.

Stack

The stack is a single linear chain of six PRs; merge bottom-up. This PR is the fourth link in that
chain and the second of the five documentation PRs. It is based on docs/adr-records (#15), not on
main, so review it after the PRs below it land or the diff will read wider than it is.

main
 └── fix/gcc-cpp-compat            #10  compile fix + ColProxy constructor
      └── cpp/format-blocking      #21  .clang-format, pinned+scoped clang-format, job blocking
           └── docs/adr-records                    #15  nine ADRs
                └── docs/runbooks                  #16  four runbooks   ← this PR
                     └── docs/roadmap-and-rust-port #17  roadmap + Rust assessment
                          └── docs/entry-documents  #18  README/CONTRIBUTING/ONBOARDING
                               └── docs/cpp-format-policy #22  ADR 0010 + cpp-job corrections

@sqr00t sqr00t changed the title docs(runbooks): development, release, CI-triage and upstream-sync runbooks (2/4) docs(runbooks): development, release, CI-triage and upstream-sync runbooks (2/5) Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant