bazel-contrib / bazel-contrib/rules_oci
incorrect docs on tars attribute in oci_image
- Dominant language
- Starlark
- Stars
- 423
- Forks
- 213
- Avg merge
- 53m
- Merged PRs (30d)
- 1
Description
The explaination of why the tars list should not be sorted in https://github.com/bazel-contrib/rules_oci/blob/main/docs/image.md?plain=1#L82
is not correct, (Dockerfile cargo-culting?)
> List of tar files to add to the image as layers. Do not sort this list; the order is preserved in the resulting image. Less-frequently changed files belong in lower layers to reduce the network bandwidth required to pull and push.
The order only affects file shadowing, when running the image as a container. (well and the tiny manifest which holds the list of layers)
Tried to rephrase in a PR, but it gets complicated and my tech writing skill are not that good.
Also 'lower' is problematic - the lowest layer would be the first layer in the overlay fs - but that is un-intutive when looking a list of tars separated with newlines
Contributor guide
Research direction
Start with the referenced passage in docs/image.md around line 82 and review the explanation of the oci_image tars attribute. Check the stated effects of tar ordering and the wording about layer placement against the issue details. Done means the documentation accurately explains the behavior and uses unambiguous layer terminology.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100