docs: walk new contributors through emitting recipe evidence#976
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughThis PR expands documentation for the recipe evidence bundle workflow across two guides. The user validation guide introduces the technical mechanics of producing evidence bundles via Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
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 |
Signed-off-by: Nathan Hensley <[email protected]>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 549-554: Add a brief inline definition of "material-slice" in this
paragraph: state which recipe fields are considered material (e.g., criteria,
component refs, constraints, validation) and which are non-material (e.g.,
comments, displayName, description, key order), so readers immediately
understand what "material-slice digest" and "material-slice canonicalization"
mean without following the ADR-007 link; keep it to one concise sentence
inserted after the first mention of "material-slice digest" or before the
ADR-007 reference.
- Around line 610-612: Update the sentence containing "fingerprint match against
the recipe's criteria" to briefly define what "fingerprint" means on first use
(for example: "fingerprint match against the recipe's criteria (the bundle's
recorded cluster characteristics such as OS, architecture, and distribution
identifiers)") or move the later clarifying sentence that mentions "fingerprint
dimensions are in the predicate" earlier so the term is explained before it's
used; ensure you edit the same paragraph that currently reads "Exit 0 means
signature, schema, inventory, manifest hashes, fingerprint match against the
recipe's criteria, and BOM cross-reference all passed" and keep the added
clarification concise and inline.
🪄 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: 2731db2c-a1e3-412f-893a-20cc76eab1f8
📒 Files selected for processing (1)
docs/integrator/recipe-development.md
mchmarny
approved these changes
May 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands the evidence-emission docs so a new recipe contributor can see, in the contributor/integrator surface, exactly how to produce and prepare an evidence bundle before opening a PR — instead of the prior hand-wave at ADR-007.
Motivation / Context
aicr validate --emit-attestationandaicr evidence verifyare shipped, but the only end-to-end walkthrough lives indemos/evidence.md. The contributor/integrator pages either skipped the topic (docs/user/validation.md— covers CNCF evidence only) or deferred it to the design doc (docs/integrator/recipe-development.md§ Submitting Your Recipe). Contributors creating brand-new recipes for hardware AICR maintainers cannot independently re-run had no task-oriented entry point.Fixes: N/A
Related: ADR-007 (
docs/design/007-recipe-evidence.md),demos/evidence.mdType of Change
Component(s) Affected
docs/,examples/)Implementation Notes
docs/user/validation.md: new## Emitting recipe evidence for a PRsection between the existing CNCF evidence section and "Input modes". Covers the producer-side--emit-attestation/--pushflow with the command, bundle layout, self-verify step, a flag-reference table, registry/Referrers-API requirements, OIDC token precedence, and the local-only fallback. Treated as a sibling to the existing CNCF-submission evidence section since both are evidence kinds emitted byaicr validate.docs/integrator/recipe-development.md: replaced the stub "Submitting Your Recipe" section with five concrete subsections written for a brand-new contributor (When You Need Evidence, Producing the Bundle, Self-Verifying Before You Open the PR, What to Include in the PR, If You Cannot Push to a Registry). Cross-links to the user/validation.md section above as the per-flag source of truth so the content does not duplicate.evidenceexempt-bypass-policy— the/inevidence/exemptis stripped without replacement).Testing
Risk Assessment
Rollout notes: N/A — additive documentation only.
Checklist
make testwith-race) — N/A, doc-onlymake lint) — N/A, doc-onlygit commit -S)