canonical / canonical/chisel-docs

`python3` example in slice design approaches contradicts itself

Open
#63 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
3
Forks
15
Avg merge
13h 41m
Merged PRs (30d)
4

Description

`python3` is used as an example twice in _"grouping by function"_, and it feels like the two uses contradict each other:

intro says:

> [`python3` slice definitions file] has a `core` slice providing a very minimal `python3` runtime, but also a `standard` slice with the additional libraries on top of `core`.

but the body says:

> A `minimal` slice that offers a stripped down installation, to the absolute essentials... Taking the above `python3` example, this slice would only contain the necessary dependencies to run a trivial "Hello World" script, and not much more.

so the intro implies `python3.core` *is* the minimal-runtime tier (no separate `minimal` slice in the SDF), while the body re-uses the same `python3` example to illustrate the actual `minimal` tier. reader cant tell whether `python3.core` corresponds to `minimal` or `core` in the canonical naming.

btw, current `python3.yaml` in `ubuntu-26.04` does not have a minimal slice, so _"taking the above python3 example, this slice would only contain..."_ references a slice that isnt in the SDF. worth rewording the body bullet as hypothetical?? -- _"if python3 had a minimal slice, it would only contain..."_. unsure about this one since it's a moving target: what if we add a minimal slice to pytohn3 tomorrow? do we update the docs yet again? feels like an unnecessary and subtle coupling of the two, but on the other hand the docs should reflect reality.

btw, btw, how about explicitly stating the superset chain? something like _"`dev` is a superset of `standard`, which is a superset of `core`, which is a superset of `minimal`"_ -- i.e. each tier has the previous one in its `essential`, so installing `dev` transitively pulls everything below. the page lists the four tiers but never says how they relate, so a reader is left to infer it from the prose (which only gestures at it via _"on top of `core`"_ in the intro and _"`dev` slice which is the `standard` slice, plus..."_ in the dev bullet).

would also be worth flagging that the chain is opt-in -- not every package needs all four tiers. slicers pick the subset that fits the package (e.g. a leaf utility might only ship `bins` + `copyright`; a runtime might ship `core` + `standard` and skip `minimal`/`dev`). otherwise readers may assume all four are mandatory.

### links

- source: https://github.com/canonical/chisel-docs/blob/8e996e3591eb0031e0e35e63d2f726764f4792a0/docs/explanation/slice-design-approaches.md?plain=1#L27-L34
- live: https://documentation.ubuntu.com/chisel/latest/explanation/slice-design-approaches/#grouping-by-function
- python3 slice in 26.04: https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/python3.yaml

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.