Skip to content

docs: add recipes section and artifacts configuration reference#81

Merged
bryantbiggs merged 1 commit into
mainfrom
docs/recipes-and-artifacts
May 4, 2026
Merged

docs: add recipes section and artifacts configuration reference#81
bryantbiggs merged 1 commit into
mainfrom
docs/recipes-and-artifacts

Conversation

@bryantbiggs

Copy link
Copy Markdown
Member

Summary

PR 4 of the tag-filter + artifacts rollout. Pure docs — no code touched. Surfaces existing knobs as named patterns so users can find them without reading the configuration reference end to end.

  • Adds a Recipes top-level section with seven pages: production-mirror, minimum-bytes, pin-literals-only, helm-chart-and-images, variant-filtering, semver-tracking, single-architecture.
  • Adds an Artifacts configuration section (enabled / include / exclude / require_artifacts) with rationale for default-on.
  • Adds a dual quickstart to README.md distinguishing full-fidelity from minimum-bytes, and surfaces the bit-for-bit framing in the tagline.
  • The single-architecture recipe lives behind a prominent warning header documenting digest divergence, broken cosign verify, and arm64-consumer failure — the only ocync recipe that opts out of bit-for-bit.

Multi-arch is preserved in every standard recipe. The platforms: filter is documented as the single existing exception to bit-for-bit and isolated to the advanced recipe.

Linked: #80 (registry URL rewriting investigation, referenced from helm-chart-and-images).

Test plan

  • npm run --prefix docs build — 28 pages built, no errors
  • All seven recipe pages render at expected paths under /recipes/
  • Cross-page links use root-absolute slugs per docs/CLAUDE.md convention
  • Astro nav (top header + sidebar) shows the new "Recipes" tab and links
  • Manual: load npm run --prefix docs preview and click through the dual quickstart and one recipe
  • Manual: confirm gh-pages deploy renders correctly under the /ocync/ base path

Surface the existing knobs (artifacts.enabled, tag filter, platforms) as named
patterns so users can find them without reading the full configuration reference
end to end. Production-fidelity is named as a deliberate choice; minimum-bytes
preserves multi-arch by default; single-architecture lives behind a warning
header documenting the bit-for-bit divergence.

Adds:
- Recipes top-level docs section with seven pages (production, minimum-bytes,
  pin-literals, helm + images, variant, semver, single-architecture)
- Artifacts configuration section with enabled/include/exclude/require_artifacts
  reference and rationale for default-on
- Dual quickstart in README distinguishing full-fidelity from minimum-bytes
- Bit-for-bit framing in the README tagline so the project's content-integrity
  promise is visible above the fold
@bryantbiggs
bryantbiggs force-pushed the docs/recipes-and-artifacts branch from 44d8430 to 41cfd75 Compare May 4, 2026 15:39
@bryantbiggs
bryantbiggs merged commit 3feaeee into main May 4, 2026
16 checks passed
@bryantbiggs
bryantbiggs deleted the docs/recipes-and-artifacts branch May 4, 2026 15:46
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