shipping-prs
Skill83 starsChanged 2 days agoMITView on GitHub
Open, merge, release a PR - branch off main, gh pr create, auto-merge, PR body, CHANGELOG entry, tagged release. "PR stuck BLOCKED", "last commit didn't land", "which check is required", "check-release failed", "STALE.md blocks git pull". Not build/test (building-and-testing), not perf baseline (benchmark-cuda).
- Reads credentials
- Commits and pushes
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- add-model-archSkill
- benchmark-cudaSkill
- building-and-testingSkill
- check-degenerationSkill
- codebase-auditSkill
- code-graphSkill
- docs-layersSkill
- docs-syncSkill
- find-stubsSkill
- numerics-bisectSkill
- quant-formatsSkill
- server-apiSkill
- sm120-cuda-expertSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
After the merge: git log -1 --stat origin/main.
- Very specific: line 26
Never fix a red advisory check by pushing into an armed PR: disable, fix, push, re-arm (a red Mock API contract on #1803).
- Very specific: line 48
Every paragraph carries a number, a path or a decision.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Shipping PRs & Releases - imp
Hard rules
| # | Rule | Detail |
| 1 | Branch off fresh origin/main, gh pr create --base main, NEVER stack | git fetch origin && git switch -c <topic> origin/main. Stacking on a squash repo caused recovery-PR cascades. Fewer, batched PRs. |
| 2 | main merges are SQUASH | PR title = final commit subject ... (#NNNN) = the CHANGELOG line at the release cut. |
| 3 | Required check = Build (ruleset 14716423) | Static gates block inside it since #1527 (scripts/ci_static_gates.sh: filesize, lanes, entrypoint, alloc, kernels, launchguards, docs, citations, hygiene). Advisory: Lint, Mock API contract, Real API contract (model-less), clang-tidy, Sanitizers. Test lanes is its own check (#1770). Read gh pr checks <n> after the merge too. |
| 4 | PRs do not edit CHANGELOG.md | Until 2026-11-15 every merged PR dirtied every open PR through it (263 of 374 commits in 30 days). PRs that share no file may be in flight together; a conflict: resolve, git commit (hook: make preflight, ~20 s). |
| 5 | Perf- or VRAM-moving change refreshes tests/perf_baseline.json IN THE SAME PR and says so | Gate 8% decode / 8% prefill / 10% own_peak_mb; scripts/gen_perf_baseline.sh (benchmark-cuda). |
The auto-merge race
auto-merge.yml arms gh pr merge --auto --squash --delete-branch the moment a non-draft owner PR is opened (opened / ready_for_review / reopened). The squash fires the instant Build is green. Armed with the AUTO_MERGE_TOKEN PAT the merge starts CI on main and deletes the branch; on the GITHUB_TOKEN fallback it does neither (#2141-#2147: 0 of 7), so run gh workflow run CI --ref main after a release merge.
- Push ALL commits before
gh pr create. Draft PRs are not armed. - After the merge:
git log -1 --stat origin/main; when a late commit changed a NUMBER, grepmainfor the corrected value (#1081 shipped disproved figures; #1082 fixed them). Lost commit precedent:a5403bd5in #718. - Late commit sequence:
gh pr merge --disable-auto <PR>FIRST, edit,make verify-fast,git push,gh pr merge --auto --squash --delete-branch, verify the squash. - A new topic that touches a file of a PR whose auto-merge is in flight starts after that merge (#1516 born conflicted 29 min after #1515, through
CHANGELOG.md, which PRs no longer edit). - Never fix a red advisory check by pushing into an armed PR: disable, fix, push, re-arm (a red
Mock API contracton #1803).
Ship sequence
git fetch origin && git switch -c <topic> origin/main
# work; then:
make preflight # CPU only: static gates, tidy + format on changed lines, actionlint
make verify-fast # measures imp:test; rebuild first (make build)
git push -u origin <topic> # NO --no-verify. scripts/pre-push.hook: make preflight; GPU verify-fast only with IMP_HOOK_GPU=1
gh pr create --base main --title "<squash subject>" --body-file <file>
git log -1 --stat origin/main # after mergegit push | tailswallows the gate block (it prints BEFORE the git lines); read the full output.IMP_HOOK_GPU=1 git pushwhile your ownverify-fastruns collides on the GPU; without it the hook touches no GPU.docs_lint.pywritesdocs/audit/docs-rewrite/STALE.mdonly with--write-stale; hooks and CI never touch it (#2194).- Moving text from
docs/ROADMAP.mdtodocs/plans/rewrites relative links (](MODELS.md)->](../MODELS.md));make preflight(both hooks) runshygiene, CIRelease hygienetoo. Local:docker run --rm -v $PWD:/src -w /src -e HOME=/tmp imp:toolchain bash -c 'git config --global --add safe.directory /src; bash scripts/ci_static_gates.sh hygiene docs citations'. - PR monitors:
pgrep -f "<string>"matches the monitor's own shell; stop an old monitor before starting a second on the same PR.
The PR body
Every paragraph carries a number, a path or a decision; reasoning goes to docs/ and the PR links it.
## <change> one section per topic, bullets under it
| | before | after | a table wherever a count or a timing moved
## Gate the measured block, pasted from the captured run, nothing wrapped around it
Not in here: one line: what a reviewer would look for and not find- Capture the gate output to a file, then paste. Never type gate numbers from memory (three wrong PR bodies in one day: #1664, #1666, #1689).
- Cut: the sentence that sets a finding up, the retelling of how a bug was found, reading instructions for the numbers. #1531 went 162 -> 57 lines with no fact lost. Same for commit messages.
CHANGELOG
- The PR title is the entry:
type(scope): what changed for the reader, the checkable number.feat-> Added,fix-> Fixed,perf/refactor/build-> Changed,docs/test/ci/chore-> Internal,type!:-> Breaking. Plain punctuation; every number names model, quant, unit. - The release cut writes the section:
python3 tools/changelog_release.py --version X.Y.Z --since vPREV(--dry-runprints it). - Hand entries under
[Unreleased]only for what a title cannot carry (a breaking change's migration line): at most 3 lines and 360 characters (tools/check_changelog_form.py, gated), into the EXISTING### ...block (a second### Addedfailscheck-release.sh). The generator moves them into the release, adds their PR number, skips that PR's generated line.
Triage: a PR that will not merge
gh pr view <PR> --json mergeStateStatus,statusCheckRollup,reviewDecision| State | Meaning | Action |
Build green, still BLOCKED | required-check name != Build | realign job name or ruleset 14716423 |
reviewDecision not APPROVED / unresolved thread | review action needed | |
gh pr checks prints NOTHING and mergeStateStatus=DIRTY | conflict with main; GitHub runs no workflow on an unbuildable merge ref, so no CI, no auto-merge, no arming | rebase onto origin/main; force-push is gated, so push a fresh branch and reopen |
mergeStateStatus=UNKNOWN | not computed yet | query again; never build a mechanism on it (#1516 cost an hour) |
Build red on a refactor that deleted or renamed cited code | citations gate: anchor of a file:line gone or ambiguous in a living doc (#1783; line drift alone only warns since #2231) | python3 scripts/check_doc_citations.py .; drift: --fix |
Test lanes red | a test in no ctest entry, or a ctest -L unit test demoted vs the base (tools/check_test_lanes.py names it) | register the module/test in CMakeLists.txt; a new GPU test in a gpu module needs no edit |
File size red | an allowlisted file past its pin ceiling (next multiple of 25) | python3 tools/check_filesize.py --update |
Cutting a tagged release
Version SSoT: CMakeLists.txt project(imp ... VERSION X.Y.Z). A release is its own PR.
- Bump
project(... VERSION X.Y.Z). CHANGELOG.md:python3 tools/changelog_release.py --version X.Y.Z --since vPREV(inimp:toolchain); read the section, fix a subject that reads wrong for a stranger.docs/BENCHMARKS.md: the**Toolchain (current: \vX.Y.Z`):**line (check-release.sh` parses exactly that form).bash scripts/check-release.sh; echo $?and read the EXIT CODE (an aborted gate prints no FAIL line, #1394). Running containers: it lists them and asksStop them for the GPU stages? [y/N], restart offered at exit; without a terminalIMP_RELEASE_STOP_CONTAINERS=yes|no(default no). Known exit-1 cause:test-spec-fidelity"skipped, card not free enough" (needs ~26 GB free after the earlier stages); runmake test-spec-fidelityseparately, read exit 0.check-release.shprints onlyPASS make verify-fast: runmake verify-fastseparately for the release-note figures;bench-competitivewrites/tmp/bench_competitive.tsv.- Merge (squash), then
git tag vX.Y.Z <sha> && git push origin vX.Y.Z. gh release create vX.Y.Z --title "vX.Y.Z: <what changed>" --notes-file <file> --verify-tag. The tag alone is not the release.
Release notes form (three headings and a footer, nothing before them; no install block, no "what imp is" paragraph, measurement conditions ride inside the numbers):
## Highlights 3-5 bullets, headline number inline, (#NNNN) for detail
## Also in here one line each: deps, refusals, guards
## Gate verify-fast on the tagged tree, model + quant + card named
No breaking changes. / Breaking: <what a user must change>
Full detail: CHANGELOG. N PRs since vX.Y.(Z-1).- Lead with what a reader can now do (a checkpoint that runs, a modality), then speed.
- PR numbers in bullets come from
git log vPREV..HEAD --oneline, not memory. - Titles name the change, not the anecdote:
v0.25.0: Nemotron-3.5-Lightning runs; Qwen3.6-35B sees images. - Negative results are findings: verdict plus number.
Common mistakes
| Symptom | Cause | Fix |
| Release only bumped one of {CMakeLists, CHANGELOG, BENCHMARKS} | bump all three |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

