From 54dda608cf5118b4a0cdd0a15d071d7eebb3ed5a Mon Sep 17 00:00:00 2001 From: lczyk Date: Thu, 24 Sep 2026 13:50:43 +0100 Subject: [PATCH 01/15] docs: split slice design approaches into content, function and tier --- docs/explanation/slice-design-approaches.md | 135 ++++++++++++++------ docs/how-to/slice-a-package.md | 2 +- 2 files changed, 99 insertions(+), 38 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index a3561eb..7f0d70c 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -1,53 +1,114 @@ --- myst: html_meta: - description: "Explanation of the two slice design approaches in Chisel: grouping by content type (bins, libs) or by functionality (minimal, core, standard)." + description: "Explanation of the three slice design approaches in Chisel: grouping by content type (bins, libs), by function (crypto, dbus-services) or by tier (minimal, core, standard, dev)." --- (slice_design_approaches)= # Slice design approaches -There are two approaches to design slices: **grouping by content** and **grouping by function**. Depending on the package, one of these approaches might be more suitable. It is up to the user to choose a preferred approach. +There are three approaches to design slices: **grouping by content**, +**grouping by function** and **grouping by tier**. Depending on the package, +one of these approaches might be more suitable. It is up to the user to choose +a preferred approach. + +The approaches are not mutually exclusive, and a single slice definitions file +can mix them. For example, the +[`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/systemd.yaml) +groups most of its contents by type (`bins`, `libs`, `config`), but also has +function slices such as `dbus-services`. ## Grouping by type of content - This means putting all the binaries together in one slice, all the libraries together in another slice, and so on. - A good example is the [`dpkg` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/dpkg.yaml). +This means putting all the binaries together in one slice, all the libraries +together in another slice, and so on. A good example is the +[`dpkg` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/dpkg.yaml). + +In this case, the best practice is to create: + +- a `bins` slice which contains all the binaries +- a `libs` slice which contains all the libraries +- a `config` slice which contains all [configuration files](#create_sdf_inspect_pkg_conffiles) +- a `scripts` slice which contains ASCII executable scripts, e.g. Python, + Perl scripts +- other slices analogously (e.g. `data`, `modules`, `services`, etc) + +You may split the above slices into more granular ones, but you should +reserve the above as a catch-all for their respective types. - In this case, the best practice is to create: - - a `bins` slice which contains all the binaries - - a `libs` slice which contains all the libraries - - a `config` slice which contains all [configuration files](#create_sdf_inspect_pkg_conffiles) - - a `scripts` slice which contains ASCII executable scripts, e.g. Python, - Perl scripts - - other slices analogously (e.g. `data`, `modules`, `services`, etc) - - You may split the above slices into more granular ones, but you should - reserve the above as a catch-all for their respective types. +(slice_design_approaches_function)= ## Grouping by function - This means grouping the contents into slices that deliver a specific - functionality. For example, the - [`python3` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/python3.yaml) - has a `core` slice providing a very minimal `python3` runtime, but also a - `standard` slice with the additional libraries on top of `core`. - - In this case, the most common is to create: - - A `minimal` slice that offers a stripped down installation, to the absolute essentials, to make the software - work. In most cases, such a minimal installation may only be useful if used as a base for another installation/ - build, where the developer adds their own additional dependencies. Taking the above `python3` example, this slice - would only contain the necessary dependencies to run a trivial "Hello World" script, and not much more. - - A `core` slice that offers a more complete, though still relatively slim installation. Although slightly larger - than minimal, core installations are meant to cover the majority of simple use cases, while also being a small and - ideal base to be extended for more complex use cases. Using `python3` as an example again, this slice could only - contain the topmost referenced modules in the standard library. - - A `standard` slice that provides a normal installation, supporting the full operation of the application, - including all the runtime libs/modules and additional utilities, but possibly still leaving out things like - debugging and development utilities. - - A `dev` slice which is the `standard` slice, plus all the debugging and dev utilities. A close-to full-size - installation, designed for development environments, but not production. - - Other slices which are scoped and named after the functionality they - provide (e.g. see the - [`libpython3.12-stdlib` slices](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/libpython3.12-stdlib.yaml)). +This means grouping the contents into slices that deliver a specific +functionality, and naming each slice after the functionality it provides. For +example, the +[`libpython3.12-stdlib` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/libpython3.12-stdlib.yaml) +splits the Python standard library into slices such as `crypto`, +`concurrency` and `internet`, and the `systemd` slice definitions file has a +`dbus-services` slice with the D-Bus service files. + +Such slices are best kept small and single-purpose, so that users can install +just the functionality they need on top of a base installation (see +[grouping by tier](#slice_design_approaches_tier)). + +(slice_design_approaches_tier)= + +## Grouping by tier + +This means grouping the contents into slices of increasing completeness, where +each tier is a superset of the previous one. For example, the +[`python3` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/python3.yaml) +has a `core` slice providing a very minimal `python3` runtime, but also a +`standard` slice with the additional libraries on top of `core`. + +In this case, the most common is to create: + +- A `minimal` slice that offers a stripped down installation, with the + absolute bare minimum which still retains the identity of the package. In + most cases, such a minimal installation may only be useful if used as a base + for another installation/build, where the developer adds their own + additional dependencies. Taking the above `python3` example, this slice would + only contain a runtime with no standard library, able to run a trivial "Hello + World" script, and not much more. +- A `core` slice that offers what is needed for basic functionality, and + nothing more. Although slightly larger than `minimal`, `core` installations + are meant to cover the majority of simple use cases, while also being a small + and ideal base to be extended for more complex use cases. Using `python3` as + an example again, this slice could only contain the topmost referenced + modules in the standard library. +- A `standard` slice that provides what most users would expect from a normal + installation, supporting the full operation of the application, including all + the runtime libs/modules and additional utilities. It still does not include + everything, leaving out things like manual pages, examples, and debugging and + development utilities. +- A `dev` slice which is the `standard` slice, plus all the debugging and dev + utilities. A close-to full-size installation, designed for development + environments, but not production. For example, the `systemd_dev` slice in + [Ubuntu 26.04](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) + adds tools such as `busctl` and `systemd-cgls` on top of `systemd_standard`. + +Not all four tiers have to be present, so only define the ones that are +meaningful for the package. However, since each tier is a superset of the +previous one, a higher tier must list the lower one in its `essential` +dependencies: + +```yaml +slices: + core: + essential: + - python3.12_core + # ... + standard: + essential: + - python3_core + - libpython3-stdlib_crypto + # ... +``` + +For most applications, the intended use is to install the `core` slice of a +package plus the [function slices](#slice_design_approaches_function) they +need, rather than a higher tier. For example, an application that only needs +Python's cryptographic modules can install `python3_core` and +`libpython3.12-stdlib_crypto` instead of `python3_standard`. diff --git a/docs/how-to/slice-a-package.md b/docs/how-to/slice-a-package.md index f524d85..e2b9632 100644 --- a/docs/how-to/slice-a-package.md +++ b/docs/how-to/slice-a-package.md @@ -265,7 +265,7 @@ Your second task is to **design the slices**. There are a few considerations to be made, such as figuring out what slices we need and the contents of those slices. -There are **two approaches** when designing slices: "grouping by type of content" or "grouping by function". More information on them can be found {ref}`here `. This guide groups slices **by type of content**. +There are **three approaches** when designing slices: "grouping by type of content", "grouping by function" or "grouping by tier". More information on them can be found {ref}`here `. This guide groups slices **by type of content**. - [ ] 2.1 **Choose the design approach that aligns best with your package** From 240aaadde856c786d330df337b413c970981c96a Mon Sep 17 00:00:00 2001 From: lczyk Date: Thu, 24 Sep 2026 15:49:22 +0100 Subject: [PATCH 02/15] docs: point slice examples at 26.04 --- docs/explanation/slice-design-approaches.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 7f0d70c..664916f 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -15,15 +15,15 @@ a preferred approach. The approaches are not mutually exclusive, and a single slice definitions file can mix them. For example, the -[`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/systemd.yaml) -groups most of its contents by type (`bins`, `libs`, `config`), but also has -function slices such as `dbus-services`. +[`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) +has tier slices (`standard`, `dev`), function slices such as `journal`, +`login` and `dbus-services`, and a `config` slice grouping contents by type. ## Grouping by type of content This means putting all the binaries together in one slice, all the libraries together in another slice, and so on. A good example is the -[`dpkg` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/dpkg.yaml). +[`dpkg` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/dpkg.yaml). In this case, the best practice is to create: @@ -44,7 +44,7 @@ reserve the above as a catch-all for their respective types. This means grouping the contents into slices that deliver a specific functionality, and naming each slice after the functionality it provides. For example, the -[`libpython3.12-stdlib` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/libpython3.12-stdlib.yaml) +[`libpython3.14-stdlib` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/libpython3.14-stdlib.yaml) splits the Python standard library into slices such as `crypto`, `concurrency` and `internet`, and the `systemd` slice definitions file has a `dbus-services` slice with the D-Bus service files. @@ -59,7 +59,7 @@ just the functionality they need on top of a base installation (see This means grouping the contents into slices of increasing completeness, where each tier is a superset of the previous one. For example, the -[`python3` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/python3.yaml) +[`python3` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/python3.yaml) has a `core` slice providing a very minimal `python3` runtime, but also a `standard` slice with the additional libraries on top of `core`. @@ -85,8 +85,7 @@ In this case, the most common is to create: development utilities. - A `dev` slice which is the `standard` slice, plus all the debugging and dev utilities. A close-to full-size installation, designed for development - environments, but not production. For example, the `systemd_dev` slice in - [Ubuntu 26.04](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) + environments, but not production. For example, the `systemd_dev` slice adds tools such as `busctl` and `systemd-cgls` on top of `systemd_standard`. Not all four tiers have to be present, so only define the ones that are @@ -98,7 +97,7 @@ dependencies: slices: core: essential: - - python3.12_core + - python3.14_core # ... standard: essential: @@ -111,4 +110,4 @@ For most applications, the intended use is to install the `core` slice of a package plus the [function slices](#slice_design_approaches_function) they need, rather than a higher tier. For example, an application that only needs Python's cryptographic modules can install `python3_core` and -`libpython3.12-stdlib_crypto` instead of `python3_standard`. +`libpython3.14-stdlib_crypto` instead of `python3_standard`. From 65eac11a43eb3cfa3e55e685299a0cc150652af3 Mon Sep 17 00:00:00 2001 From: lczyk Date: Thu, 24 Sep 2026 15:56:53 +0100 Subject: [PATCH 03/15] docs: remove outdated yaml example from slice design tiers --- docs/explanation/slice-design-approaches.md | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 664916f..082c07f 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -91,20 +91,7 @@ In this case, the most common is to create: Not all four tiers have to be present, so only define the ones that are meaningful for the package. However, since each tier is a superset of the previous one, a higher tier must list the lower one in its `essential` -dependencies: - -```yaml -slices: - core: - essential: - - python3.14_core - # ... - standard: - essential: - - python3_core - - libpython3-stdlib_crypto - # ... -``` +dependencies. For most applications, the intended use is to install the `core` slice of a package plus the [function slices](#slice_design_approaches_function) they From 3c195cb63187a3e3872090efe1f6431e9b74d23a Mon Sep 17 00:00:00 2001 From: lczyk Date: Thu, 24 Sep 2026 16:00:57 +0100 Subject: [PATCH 04/15] docs: clarify use of standard vs core slices explain when to use standard (regular installation behaviour) vs core with function slices (to minimise root filesystem footprint). --- docs/explanation/slice-design-approaches.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 082c07f..d4b5eae 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -93,8 +93,10 @@ meaningful for the package. However, since each tier is a superset of the previous one, a higher tier must list the lower one in its `essential` dependencies. -For most applications, the intended use is to install the `core` slice of a -package plus the [function slices](#slice_design_approaches_function) they -need, rather than a higher tier. For example, an application that only needs +`standard` is the convenient choice when the package should behave like a +regular installation. Applications that only need part of a package should +instead install the `core` slice plus the +[function slices](#slice_design_approaches_function) they use, which keeps the +root file system smaller. For example, an application that only needs Python's cryptographic modules can install `python3_core` and `libpython3.14-stdlib_crypto` instead of `python3_standard`. From 7f182cea6363b93f919a51b7ed3843488f3d9201 Mon Sep 17 00:00:00 2001 From: lczyk Date: Fri, 25 Sep 2026 16:13:36 +0100 Subject: [PATCH 05/15] docs: move note on mixing slice design approaches to the end --- docs/explanation/slice-design-approaches.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index d4b5eae..db82693 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -13,12 +13,6 @@ There are three approaches to design slices: **grouping by content**, one of these approaches might be more suitable. It is up to the user to choose a preferred approach. -The approaches are not mutually exclusive, and a single slice definitions file -can mix them. For example, the -[`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) -has tier slices (`standard`, `dev`), function slices such as `journal`, -`login` and `dbus-services`, and a `config` slice grouping contents by type. - ## Grouping by type of content This means putting all the binaries together in one slice, all the libraries @@ -100,3 +94,11 @@ instead install the `core` slice plus the root file system smaller. For example, an application that only needs Python's cryptographic modules can install `python3_core` and `libpython3.14-stdlib_crypto` instead of `python3_standard`. + +## Mixing approaches + +The approaches are not mutually exclusive, and a single slice definitions file +can mix them. For example, the +[`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) +has tier slices (`standard`, `dev`), function slices such as `journal`, +`login` and `dbus-services`, and a `config` slice grouping contents by type. From 730db9d3825cd81488fd79091f61706fcc4e7006 Mon Sep 17 00:00:00 2001 From: lczyk Date: Fri, 25 Sep 2026 16:13:52 +0100 Subject: [PATCH 06/15] docs: match slice design approach names to headings --- docs/explanation/slice-design-approaches.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index db82693..544742a 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -8,7 +8,7 @@ myst: # Slice design approaches -There are three approaches to design slices: **grouping by content**, +There are three approaches to design slices: **grouping by type of content**, **grouping by function** and **grouping by tier**. Depending on the package, one of these approaches might be more suitable. It is up to the user to choose a preferred approach. From 91089b6adfe0e703f92bb3577fa9c3c6d6e59227 Mon Sep 17 00:00:00 2001 From: lczyk Date: Fri, 25 Sep 2026 16:14:03 +0100 Subject: [PATCH 07/15] docs: reserve tier slice names --- docs/explanation/slice-design-approaches.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 544742a..7dccb0b 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -82,6 +82,9 @@ In this case, the most common is to create: environments, but not production. For example, the `systemd_dev` slice adds tools such as `busctl` and `systemd-cgls` on top of `systemd_standard`. +You should reserve the above names for their respective tiers, and not use +them for slices with a different purpose. + Not all four tiers have to be present, so only define the ones that are meaningful for the package. However, since each tier is a superset of the previous one, a higher tier must list the lower one in its `essential` From c80661e9f05d21abd44ec06a14f05e8aea21d4ee Mon Sep 17 00:00:00 2001 From: Marcin Konowalczyk Date: Sun, 27 Sep 2026 20:42:30 +0100 Subject: [PATCH 08/15] Apply batched suggestions from code review Co-authored-by: Anna Sancho Vaquer Signed-off-by: Marcin Konowalczyk --- docs/explanation/slice-design-approaches.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 7dccb0b..f5ec56d 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -1,7 +1,7 @@ --- myst: html_meta: - description: "Explanation of the three slice design approaches in Chisel: grouping by content type (bins, libs), by function (crypto, dbus-services) or by tier (minimal, core, standard, dev)." + description: "Explanation of the three slice design approaches in Chisel: grouping by content type (bins, libs), function (crypto, dbus-services) or tier (minimal, core)." --- (slice_design_approaches)= @@ -77,7 +77,7 @@ In this case, the most common is to create: the runtime libs/modules and additional utilities. It still does not include everything, leaving out things like manual pages, examples, and debugging and development utilities. -- A `dev` slice which is the `standard` slice, plus all the debugging and dev +- A `dev` slice that includes all the debugging and dev utilities. A close-to full-size installation, designed for development environments, but not production. For example, the `systemd_dev` slice adds tools such as `busctl` and `systemd-cgls` on top of `systemd_standard`. From e294af3c54b3360e6aed3002a49d624e17c70517 Mon Sep 17 00:00:00 2001 From: lczyk Date: Sun, 27 Sep 2026 20:49:19 +0100 Subject: [PATCH 09/15] docs: address review comments --- docs/explanation/slice-design-approaches.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index f5ec56d..26fbe47 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -1,7 +1,7 @@ --- myst: html_meta: - description: "Explanation of the three slice design approaches in Chisel: grouping by content type (bins, libs), function (crypto, dbus-services) or tier (minimal, core)." + description: "Explanation of the three slice design approaches in Chisel: grouping by content type (bins, libs), function (crypto, internet) or tier (minimal, core)." --- (slice_design_approaches)= @@ -13,6 +13,12 @@ There are three approaches to design slices: **grouping by type of content**, one of these approaches might be more suitable. It is up to the user to choose a preferred approach. +Whichever the approach, the slices do not have to cover all the contents of a +package. It is fine to leave out files that no slice needs, such as manual pages +or examples. + +(slice_design_approaches_content)= + ## Grouping by type of content This means putting all the binaries together in one slice, all the libraries @@ -40,8 +46,7 @@ functionality, and naming each slice after the functionality it provides. For example, the [`libpython3.14-stdlib` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/libpython3.14-stdlib.yaml) splits the Python standard library into slices such as `crypto`, -`concurrency` and `internet`, and the `systemd` slice definitions file has a -`dbus-services` slice with the D-Bus service files. +`concurrency` and `internet`. Such slices are best kept small and single-purpose, so that users can install just the functionality they need on top of a base installation (see @@ -59,7 +64,7 @@ has a `core` slice providing a very minimal `python3` runtime, but also a In this case, the most common is to create: -- A `minimal` slice that offers a stripped down installation, with the +- A `minimal` slice that offers a stripped down, base installation, with the absolute bare minimum which still retains the identity of the package. In most cases, such a minimal installation may only be useful if used as a base for another installation/build, where the developer adds their own @@ -98,10 +103,12 @@ root file system smaller. For example, an application that only needs Python's cryptographic modules can install `python3_core` and `libpython3.14-stdlib_crypto` instead of `python3_standard`. +(slice_design_approaches_mixing)= + ## Mixing approaches The approaches are not mutually exclusive, and a single slice definitions file can mix them. For example, the [`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) -has tier slices (`standard`, `dev`), function slices such as `journal`, -`login` and `dbus-services`, and a `config` slice grouping contents by type. +has tier (`standard`, `dev`), function (`journal`, `login`, `dbus-services`), +and content type slices (`config`). From 7fdcaa1b1e9ac1c5a00844c69991779a9a267476 Mon Sep 17 00:00:00 2001 From: lczyk Date: Tue, 13 Oct 2026 13:01:24 +0100 Subject: [PATCH 10/15] docs: turn mixing slice design approaches into a note --- docs/explanation/slice-design-approaches.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 26fbe47..74ce994 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -49,8 +49,7 @@ splits the Python standard library into slices such as `crypto`, `concurrency` and `internet`. Such slices are best kept small and single-purpose, so that users can install -just the functionality they need on top of a base installation (see -[grouping by tier](#slice_design_approaches_tier)). +just the functionality they need on top of a base installation. (slice_design_approaches_tier)= @@ -103,12 +102,10 @@ root file system smaller. For example, an application that only needs Python's cryptographic modules can install `python3_core` and `libpython3.14-stdlib_crypto` instead of `python3_standard`. -(slice_design_approaches_mixing)= - -## Mixing approaches - -The approaches are not mutually exclusive, and a single slice definitions file -can mix them. For example, the +:::{note} +These approaches can be combined in one slice definitions file. For example, +the [`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) -has tier (`standard`, `dev`), function (`journal`, `login`, `dbus-services`), -and content type slices (`config`). +uses tier slices (`standard`, `dev`), function slices (`journal`, `login`, +`dbus-services`) and a content type slice (`config`). +::: From 8a7abfa394c2ef135420aeb242889ce5570782bd Mon Sep 17 00:00:00 2001 From: lczyk Date: Tue, 13 Oct 2026 13:02:41 +0100 Subject: [PATCH 11/15] docs: tidy slice tier wording --- docs/explanation/slice-design-approaches.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 74ce994..c0a9f15 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -58,7 +58,7 @@ just the functionality they need on top of a base installation. This means grouping the contents into slices of increasing completeness, where each tier is a superset of the previous one. For example, the [`python3` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/python3.yaml) -has a `core` slice providing a very minimal `python3` runtime, but also a +has a `core` slice providing a small `python3` runtime, but also a `standard` slice with the additional libraries on top of `core`. In this case, the most common is to create: @@ -81,10 +81,10 @@ In this case, the most common is to create: the runtime libs/modules and additional utilities. It still does not include everything, leaving out things like manual pages, examples, and debugging and development utilities. -- A `dev` slice that includes all the debugging and dev - utilities. A close-to full-size installation, designed for development - environments, but not production. For example, the `systemd_dev` slice - adds tools such as `busctl` and `systemd-cgls` on top of `systemd_standard`. +- A `dev` slice that includes all the debugging and dev utilities. A + close-to full-size installation, designed for development environments, but + not production. For example, the `systemd_dev` slice adds tools such as + `busctl` and `systemd-cgls` on top of `systemd_standard`. You should reserve the above names for their respective tiers, and not use them for slices with a different purpose. From 7645e022947590ff45ad969cbd2957ab050e80a2 Mon Sep 17 00:00:00 2001 From: Marcin Konowalczyk Date: Wed, 14 Oct 2026 10:32:04 +0100 Subject: [PATCH 12/15] Update docs/explanation/slice-design-approaches.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: Marcin Konowalczyk --- docs/explanation/slice-design-approaches.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index c0a9f15..c8611c0 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -61,7 +61,7 @@ each tier is a superset of the previous one. For example, the has a `core` slice providing a small `python3` runtime, but also a `standard` slice with the additional libraries on top of `core`. -In this case, the most common is to create: +In this case, the most common approach is to create: - A `minimal` slice that offers a stripped down, base installation, with the absolute bare minimum which still retains the identity of the package. In From 550ddf4f9addae7b2c5a24309effa64e643a580d Mon Sep 17 00:00:00 2001 From: Marcin Konowalczyk Date: Wed, 14 Oct 2026 10:32:13 +0100 Subject: [PATCH 13/15] Update docs/explanation/slice-design-approaches.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: Marcin Konowalczyk --- docs/explanation/slice-design-approaches.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index c8611c0..4f2f14f 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -102,10 +102,10 @@ root file system smaller. For example, an application that only needs Python's cryptographic modules can install `python3_core` and `libpython3.14-stdlib_crypto` instead of `python3_standard`. -:::{note} +```{note} These approaches can be combined in one slice definitions file. For example, the [`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) uses tier slices (`standard`, `dev`), function slices (`journal`, `login`, `dbus-services`) and a content type slice (`config`). -::: +``` From e4c7c6fa6acdecf57c32b1da6dae9d68f45af612 Mon Sep 17 00:00:00 2001 From: lczyk Date: Fri, 16 Oct 2026 09:38:25 +0100 Subject: [PATCH 14/15] docs: move slice approach mixing note into intro --- docs/explanation/slice-design-approaches.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 4f2f14f..d7ab663 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -17,6 +17,14 @@ Whichever the approach, the slices do not have to cover all the contents of a package. It is fine to leave out files that no slice needs, such as manual pages or examples. +```{note} +These approaches can be combined in one slice definitions file. For example, +the +[`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) +uses tier slices (`standard`, `dev`), function slices (`journal`, `login`, +`dbus-services`) and a content type slice (`config`). +``` + (slice_design_approaches_content)= ## Grouping by type of content @@ -101,11 +109,3 @@ instead install the `core` slice plus the root file system smaller. For example, an application that only needs Python's cryptographic modules can install `python3_core` and `libpython3.14-stdlib_crypto` instead of `python3_standard`. - -```{note} -These approaches can be combined in one slice definitions file. For example, -the -[`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) -uses tier slices (`standard`, `dev`), function slices (`journal`, `login`, -`dbus-services`) and a content type slice (`config`). -``` From 8061a73554ea152dcdb5ed495887ba03754bee09 Mon Sep 17 00:00:00 2001 From: Marcin Konowalczyk Date: Fri, 16 Oct 2026 10:00:27 +0100 Subject: [PATCH 15/15] feat: update explanation of slice design approaches Clarify the relationship between slice tiers and their dependencies. Signed-off-by: Marcin Konowalczyk --- docs/explanation/slice-design-approaches.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index d7ab663..cc80883 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -98,9 +98,9 @@ You should reserve the above names for their respective tiers, and not use them for slices with a different purpose. Not all four tiers have to be present, so only define the ones that are -meaningful for the package. However, since each tier is a superset of the -previous one, a higher tier must list the lower one in its `essential` -dependencies. +meaningful for the package. Each tier is a superset of the previous one. +Therefore, if more than one tier is present, the higher tier must list +the lower one in its `essential` dependencies. `standard` is the convenient choice when the package should behave like a regular installation. Applications that only need part of a package should