docs: add maintainer runbook for evidence-backed recipe PRs#972
Conversation
Adds docs/contributor/maintaining.md as the maintainer-side view of the recipe-evidence flow described in ADR-007, links it from the integrator recipe-development guide, and registers it in the docs nav. ADR-007 is updated to defer the tarball input form for `aicr evidence verify` to V2 (pointer / OCI / unpacked directory ship in V1; tarballs unpack-and-verify via the directory path).
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Enterprise Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThis PR adds docs: a new maintainer runbook (docs/contributor/maintaining.md) describing reviewer checklists, signer-identity treatment, Exit-1 process, evidence/exempt policy, and a 6-month audit runbook; it refines ADR-007 to remove tarball auto-detection from V1 aicr evidence verify inputs (leaving pointer, OCI ref, and unpacked directory); and it updates docs navigation and integrator guidance to link the new runbook. Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/integrator/recipe-development.md`:
- Around line 527-529: Replace the unclear opening sentence in the "Submitting
Your Recipe" section that currently begins with "Recipes that target hardware
AICR maintainers cannot independently re-run require an evidence bundle..." with
a concise, unambiguous sentence such as: "If a recipe targets hardware only
accessible to AICR maintainers, contributors must attach an evidence bundle so
reviewers can verify the recipe without owning the hardware." Update the
sentence in that section (look for the existing fragment about recipes targeting
hardware AICR maintainers) to use this clearer wording and ensure surrounding
sentences flow grammatically.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 57fc3cb8-6d7d-46c4-b9e3-d6cd9430f907
📒 Files selected for processing (4)
docs/contributor/maintaining.mddocs/design/007-recipe-evidence.mddocs/index.ymldocs/integrator/recipe-development.md
2 participants
Summary
Adds a maintainer-facing runbook for reviewing recipe contributions backed by ADR-007 evidence bundles, and trims ADR-007 to defer tarball input form to V2.
Motivation / Context
Maintainers cannot independently re-run a contributor's validator on hardware they don't have. ADR-007 specifies the trust artifact (signed evidence bundle) that lets a maintainer accept a recipe they cannot reproduce, but until now there was no maintainer-side runbook describing how to review such PRs in practice. This adds that page and wires it into the integrator guide and docs nav.
ADR-007 is also tightened: the V1 verifier input forms are pointer / OCI / unpacked directory. Tarballs are deferred to V2 (contributors can unpack and verify via the directory path in the meantime), keeping the V1 surface minimal.
Fixes: N/A
Related: ADR-007
Type of Change
Component(s) Affected
docs/,examples/)Implementation Notes
docs/contributor/maintaining.mdcovers: review checklist for PRs touchingrecipes/**, signer-identity trust patterns, exit-1 review process, and pointers back to ADR-007 for the bundle format.docs/integrator/recipe-development.mdand registered indocs/index.ymlnav.Testing
Docs-only change.
make qualifynot strictly required for prose, but lychee anchor checks ondocs/**will run in CI on push.Risk Assessment
Rollout notes: N/A
Checklist
make testwith-race) — N/A, docs-onlymake lint) — N/A, docs-onlygit commit -S)