docs: consolidate build metadata and buildkit reference docs#24847
Open
dvdksn wants to merge 5 commits intodocker:mainfrom
Open
docs: consolidate build metadata and buildkit reference docs#24847dvdksn wants to merge 5 commits intodocker:mainfrom
dvdksn wants to merge 5 commits intodocker:mainfrom
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
dvdksn
force-pushed
the
consolidate-upstream-prose
branch
from
4c4831c to
83abd69
Compare
Remove the hugo module mounts that vendored buildkitd.toml.md, slsa-definitions.md, and attestation-storage.md from moby/buildkit into this repo. These files document BuildKit internals (worker backends, frontends, attestation storage) that aren't in scope for docs.docker.com to explain — attempting to paraphrase them without the internals context produces vague, unreliable reference docs. Inbound links to the former toml-configuration page now point to the authoritative file in moby/buildkit. The task-oriented Configure BuildKit page (configure.md) continues to cover common Docker Build customizations like mirrors and CNI. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Move the /build/metadata/attestations/ subsection into three siblings under /build/metadata/: annotations, provenance, sbom. The new /metadata/_index.md becomes a rendered landing page with mechanics content (create, storage, manifest format) inherited from the old attestations index, and cross-links to the DHI core-concepts page for the underlying concept. Aliases preserved: /build/attestations/, /build/metadata/attestations/, /build/attestations/sbom/, /build/attestations/slsa-provenance/, and the /build/metadata/attestations/* equivalents. All 27 inbound links across content/ rewritten to target the new paths. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Rewrite the opening paragraph to define attestations in general terms before framing them in a DHI-specific context, consistent with other pages under core-concepts/. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add backward-compat aliases so links to the pre-flatten URLs /build/metadata/attestations/sbom/ and /build/metadata/attestations/slsa-provenance/ continue to resolve. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Will need upstream patch Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
dvdksn
force-pushed
the
consolidate-upstream-prose
branch
from
83abd69 to
e86bac9
Compare
Contributor
Author
|
/review |
![docker-agent[bot]](https://avatars.githubusercontent.com/in/2787757?s=60&v=4){kind=small}
| @@ -332,12 +332,6 @@ module: | |||
| - source: frontend/dockerfile/docs/rules | |||
Contributor
There was a problem hiding this comment.
[HIGH] Missing redirect for removed page /build/buildkit/toml-configuration/
The hugo.yaml mount that served buildkitd.toml.md at content/manuals/build/buildkit/toml-configuration.md is being removed. This means the URL /build/buildkit/toml-configuration/ will return 404 after this PR is merged — with no redirect in place.
Inbound links from configure.md and garbage-collection.md have been updated to point to the upstream GitHub URL. However, external sites, search engines, and any bookmarked links will hit a dead end.
Consider adding to content/manuals/build/buildkit/configure.md (or a stub page):
aliases:
- /build/buildkit/toml-configuration/| @@ -168,7 +169,7 @@ $ docker buildx build --tag <namespace>/<image>:<version> \ | |||
| For more information about SLSA Provenance v1, see the | |||
| [SLSA specification](https://slsa.dev/spec/v1.1/provenance). To see the | |||
| difference between SLSA v0.2 and v1 provenance attestations, refer to | |||
Contributor
There was a problem hiding this comment.
[MEDIUM] Missing period at end of sentence
The sentence ends without a period:
difference between SLSA v0.2 and v1 provenance attestations, refer to
[SLSA definitions](https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md)
Should end with a period: ...slsa-definitions.md).
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
1 participant
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
Two cleanups in the build docs:
Flatten attestations.
/build/metadata/attestations/becomes three siblings: Annotations, Provenance, SBOM. Conceptual framing moves out of the build docs and intodhi/core-concepts/attestations.md, which now leads with the concept. Aliases preserve the old URLs.Stop republishing BuildKit internals. Dropped the Hugo mounts for
buildkitd.toml.md,slsa-definitions.md, andattestation-storage.md— we can't paraphrase BuildKit internals faithfully without the internals context. Inbound links now point at the canonical files inmoby/buildkit.Generated by Claude Code