bazel-contrib / bazel-contrib/rules_oci

incorrect docs on tars attribute in oci_image

Open
#853 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.