From 06ba58180c9de46bb251ad16525e3a9717f29eae Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Mon, 16 Feb 2026 18:23:22 +0100 Subject: [PATCH 01/10] docs: add v3 format and compatibility matrix --- docs/reference/chisel-releases/chisel.yaml.md | 32 +++++++++++++++++-- .../chisel-releases/slice-definitions.md | 14 ++++++-- 2 files changed, 42 insertions(+), 4 deletions(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index b56f38d..13b521e 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -24,7 +24,7 @@ directory. | Field | Type | Required | Supported values | | -------- | -------- | -------- | ---------------- | -| `format` | `string` | Required | `v1`, `v2` | +| `format` | `string` | Required | `v1`, `v2`, `v3` | Used to define the supported schemas for the {ref}`chisel-releases_ref`. For example: @@ -33,11 +33,26 @@ For example: format: v1 ``` -```{note} +```{important} New formats are typically introduced with new _chisel-releases_ and may introduce disruptive changes to the previous formats. ``` + +(chisel_yaml_format_spec_compatibility_matrix)= + +#### Compatibility matrix + + +| chisel-release |
`v1` | Format
`v2` |
`v3` | +| -------------- | :------------: | :------------: | :------------: | +| {{20.04}} | {{all Chisel versions}} | x | x | +| {{22.04}} | {{all Chisel versions}} | x | x | +| {{24.04}} | {{all Chisel versions}} | x | x | +| {{25.10}} | x | >={{v1.2.0}} | x | +| {{26.04}} | x | x | >={{v1.4.0}} | + + (chisel_yaml_format_spec_archives)= ### `archives` @@ -380,3 +395,16 @@ public-keys: =9AdM -----END PGP PUBLIC KEY BLOCK----- ``` + + + + + +[20.04]: https://github.com/canonical/chisel-releases/tree/ubuntu-20.04 +[22.04]: https://github.com/canonical/chisel-releases/tree/ubuntu-22.04 +[24.04]: https://github.com/canonical/chisel-releases/tree/ubuntu-24.04 +[25.10]: https://github.com/canonical/chisel-releases/tree/ubuntu-25.10 +[26.04]: https://github.com/canonical/chisel-releases/tree/ubuntu-26.04 +[all chisel versions]: https://github.com/canonical/chisel/releases +[v1.2.0]: https://github.com/canonical/chisel/releases/tag/v1.2.0 +[v1.4.0]: https://github.com/canonical/chisel/releases/tag/v1.4.0 \ No newline at end of file diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index 1f1b4ab..8596a0f 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -67,12 +67,22 @@ archive: ubuntu ### `essential` +`````{tab-set} +````{tab-item} formats `v1` and `v2` +a +```` +````{tab-item} format `v3` +a +```` +````` + | Field | Type | Required | Supported values | | ----------- | --------------- | -------- | ------------------ | | `essential` | `array` | Optional | An existing slice. | +| `essential` | `array` | Optional | An existing slice. | + -Lists the slices that are needed for **every slice** of the -current package. Slices in this list must be written in their full name, e.g. + Slices in this list must be written in their full name, e.g. `hello_copyright`. This field is similar to {ref}`slice_definitions_format_slices_essential`, but applicable for every slice within the package. From bab3934d27215ce56375834127fadfeca56c48f3 Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Tue, 17 Feb 2026 18:52:41 +0100 Subject: [PATCH 02/10] docs: define format differences for slice definitions schema --- docs/reference/chisel-releases/chisel.yaml.md | 15 ++- .../chisel-releases/slice-definitions.md | 126 +++++++++++++++--- 2 files changed, 114 insertions(+), 27 deletions(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index 13b521e..b93b7cb 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -43,14 +43,17 @@ introduce disruptive changes to the previous formats. #### Compatibility matrix +In this table, you'll find the designated `format` for all existing +and supported {ref}`chisel-releases_ref`, alongside the Chisel tool versions +that support said `format`. -| chisel-release |
`v1` | Format
`v2` |
`v3` | +| chisel-release |
v1 | Format
v2 |
v3 | | -------------- | :------------: | :------------: | :------------: | -| {{20.04}} | {{all Chisel versions}} | x | x | -| {{22.04}} | {{all Chisel versions}} | x | x | -| {{24.04}} | {{all Chisel versions}} | x | x | -| {{25.10}} | x | >={{v1.2.0}} | x | -| {{26.04}} | x | x | >={{v1.4.0}} | +| [20.04] | [all Chisel versions] | x | x | +| [22.04] | [all Chisel versions] | x | x | +| [24.04] | [all Chisel versions] | x | x | +| [25.10] | x | >= [v1.2.0] | x | +| [26.04] | x | x | >= [v1.4.0] | (chisel_yaml_format_spec_archives)= diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index 8596a0f..ef4de4b 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -67,25 +67,56 @@ archive: ubuntu ### `essential` +This field is similar to {ref}`slice_definitions_format_slices_essential`, +but applicable for every slice within the package. + +```{note} +`essential` has different types across different +{ref}`formats`. +``` + `````{tab-set} -````{tab-item} formats `v1` and `v2` -a -```` -````{tab-item} format `v3` -a + +````{tab-item} Format **v3** +| Field | Type | Required | +| ----------- | -------- | -------- | +| `essential` | `object` | Optional | + +A map of slices, in their full name (e.g. `hello_copyright`), +alongside their `essential`-specific properties. + +#### `essential..arch` + +| Field | Type | Required | Supported values | +| ------ | --------------------------- | -------- | ---------------------------------------------------------------- | +| `arch` | `string` or `array` | Optional | `amd64`, `arm64`, `armhf`, `i386`, `ppc64el`, `riscv64`, `s390x` | + +Used to specify the package architectures an _essential_ dependency should be +installed for. This field can take a single architecture string or a list, as its +value. + +In the following example, `hello_copyright` will be installed for every installation +of every slice of the `hello` package, while `foo_bar` will only be installed +for `arm64` installations of any slice within `hello`. + +```yaml +package: hello +essential: + hello_copyright: {} + foo_bar: {arch: arm64} +slices: + ... +``` + ```` -````` +````{tab-item} Formats **v1** and **v2** | Field | Type | Required | Supported values | | ----------- | --------------- | -------- | ------------------ | -| `essential` | `array` | Optional | An existing slice. | | `essential` | `array` | Optional | An existing slice. | - - Slices in this list must be written in their full name, e.g. -`hello_copyright`. This field is similar to -{ref}`slice_definitions_format_slices_essential`, but applicable for every slice -within the package. +Slices in this list must be written in their full name, e.g. +`hello_copyright`. In the following example, the `hello_copyright` slice is an _essential_ for every slice including the `hello_bins` slice. @@ -101,6 +132,9 @@ slices: copyright: ... ``` +```` +````` + (slice_definitions_format_slices)= @@ -140,15 +174,60 @@ slices: ### `slices..essential` +This field is similar to {ref}`slice_definitions_format_essential`,but only applicable for the current +slice. + +```{note} +`slices..essential` has different types across different +{ref}`formats`. +``` + +`````{tab-set} + +````{tab-item} Format **v3** +| Field | Type | Required | +| ----------- | -------- | -------- | +| `essential` | `object` | Optional | + +A map of slices, and their `essential`-specific properties, that are needed and that must be installed before +the current slice. +These slice names must be written in their full name e.g. `hello_copyright`. + + +#### `slices..essential..arch` + +| Field | Type | Required | Supported values | +| ------ | --------------------------- | -------- | ---------------------------------------------------------------- | +| `arch` | `string` or `array` | Optional | `amd64`, `arm64`, `armhf`, `i386`, `ppc64el`, `riscv64`, `s390x` | + +Used to specify the package architectures an _essential_ dependency should be +installed for. This field can take a single architecture string or a list, as its +value. + +In the following example: + - `gcc-aarch64-linux-gnu_gcc` is a requirement for the `gcc` slice, only on `arm64` installations, + - `gcc-x86-64-linux-gnu_gcc` is a requirement for the `gcc` slice, only on `amd64` installations, and + - `gcc-15_gcc-15` is a requirement for the `gcc` slice, for all installations. + +```yaml +slices: + gcc: + essential: + gcc-aarch64-linux-gnu_gcc: {arch: [arm64]} + gcc-x86-64-linux-gnu_gcc: {arch: [amd64]} + gcc-15_gcc-15: + +``` +```` + +````{tab-item} Formats **v1** and **v2** | Field | Type | Required | Supported values | | ----------- | --------------- | -------- | ------------------ | | `essential` | `array` | Optional | An existing slice. | Lists the slices that are needed and that must be installed before the current slice. Slices in this list must be written in their full name -e.g. `hello_copyright`. This field is similar to -{ref}`slice_definitions_format_essential`, but only applicable for the current -slice. +e.g. `hello_copyright`. In the following example, `libc6_libs` is a requirement for the `bins` slice and must be installed when installing the `bins` slice. @@ -159,6 +238,11 @@ slices: essential: - libc6_libs ``` +```` + + +````` + (slice_definitions_format_slices_contents)= @@ -384,9 +468,9 @@ In the following example, Chisel creates the `/var/lib/chisel` directory with ### `slices..contents..prefer` -| Field | Type | Required | -| ---------- | -------- | -------- | -| `prefer` | `string` | Optional | +| Field | Type | Required | Format compatibility | +| ---------- | -------- | -------- | -------- | +| `prefer` | `string` | Optional | >= {ref}`v2` | Used to resolve a path conflict across multiple packages. @@ -491,9 +575,9 @@ and the files inside are not present in the final root file system. ### `slices..hint` -| Field | Type | Required | -| ------ | -------- | -------- | -| `hint` | `string` | Optional | +| Field | Type | Required | Format compatibility | +| ------ | -------- | -------- | -------------------- | +| `hint` | `string` | Optional | >= {ref}`v3` | Provides a concise and unopinionated discriminator to help the user select slices. It focuses on describing the *subset* of contents coming from this slice. It does From f8a8bb1fbc721a965063982a9575effbc2acda5c Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Tue, 17 Feb 2026 18:57:16 +0100 Subject: [PATCH 03/10] fix: links --- docs/reference/chisel-releases/chisel.yaml.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index b93b7cb..e9f270d 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -138,7 +138,7 @@ the archive behaviour. Lists the archive suites to fetch packages from. Read more about suites in the [Ubuntu packaging -guide](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/latest/explanation/archive/#suite). +guide](https://documentation.ubuntu.com/project/#suite). (chisel_yaml_format_spec_archives_components)= @@ -151,7 +151,7 @@ guide](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/latest Lists the components of the archive suites to fetch packages from. Read more about components in the [Ubuntu packaging -guide](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/latest/explanation/archive/#components). +guide](https://documentation.ubuntu.com/project/#components). Chisel reads the `InRelease` files from each `(suite, component)` combination to locate packages. From e7e998aadb4ea6307342302ec2b0a62e1dc19289 Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Wed, 18 Feb 2026 10:10:31 +0100 Subject: [PATCH 04/10] fix: links to anchors --- docs/reference/chisel-releases/chisel.yaml.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index e9f270d..affc4f1 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -138,7 +138,7 @@ the archive behaviour. Lists the archive suites to fetch packages from. Read more about suites in the [Ubuntu packaging -guide](https://documentation.ubuntu.com/project/#suite). +guide](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/package-archive/#suite). (chisel_yaml_format_spec_archives_components)= @@ -151,7 +151,7 @@ guide](https://documentation.ubuntu.com/project/#suite). Lists the components of the archive suites to fetch packages from. Read more about components in the [Ubuntu packaging -guide](https://documentation.ubuntu.com/project/#components). +guide](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/package-archive/#components). Chisel reads the `InRelease` files from each `(suite, component)` combination to locate packages. From 9cab0642a52b2b5eca3673345770f868d24d35c9 Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Wed, 18 Feb 2026 16:37:14 +0100 Subject: [PATCH 05/10] Update docs/reference/chisel-releases/chisel.yaml.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: Cristovao Cordeiro --- docs/reference/chisel-releases/chisel.yaml.md | 25 +++++++++++++------ 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index affc4f1..2faf7b8 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -47,14 +47,23 @@ In this table, you'll find the designated `format` for all existing and supported {ref}`chisel-releases_ref`, alongside the Chisel tool versions that support said `format`. -| chisel-release |
v1 | Format
v2 |
v3 | -| -------------- | :------------: | :------------: | :------------: | -| [20.04] | [all Chisel versions] | x | x | -| [22.04] | [all Chisel versions] | x | x | -| [24.04] | [all Chisel versions] | x | x | -| [25.10] | x | >= [v1.2.0] | x | -| [26.04] | x | x | >= [v1.4.0] | - +```{eval-rst} + ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| chisel-release | .. centered:: Format | ++=============================================================================+=======================================================+===================================================================+===================================================================+ +| | **V1** | **V2** | **V3** | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `20.04 `_ | `all `_ | x | x | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `22.04 `_ | `all `_ | x | x | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `24.04 `_ | `all `_ | x | x | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `25.10 `_ | x | >= `v1.2.0 `_| x | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `26.04 `_ | x | x | >= `v1.4.0 `_| ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ (chisel_yaml_format_spec_archives)= From b6b6f388b83c104777a2d5e92b7cfa2301dcc115 Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Wed, 18 Feb 2026 16:38:27 +0100 Subject: [PATCH 06/10] Update docs/reference/chisel-releases/chisel.yaml.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: Cristovao Cordeiro --- docs/reference/chisel-releases/chisel.yaml.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index 2faf7b8..10db6b7 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -409,14 +409,3 @@ public-keys: ``` - - - -[20.04]: https://github.com/canonical/chisel-releases/tree/ubuntu-20.04 -[22.04]: https://github.com/canonical/chisel-releases/tree/ubuntu-22.04 -[24.04]: https://github.com/canonical/chisel-releases/tree/ubuntu-24.04 -[25.10]: https://github.com/canonical/chisel-releases/tree/ubuntu-25.10 -[26.04]: https://github.com/canonical/chisel-releases/tree/ubuntu-26.04 -[all chisel versions]: https://github.com/canonical/chisel/releases -[v1.2.0]: https://github.com/canonical/chisel/releases/tag/v1.2.0 -[v1.4.0]: https://github.com/canonical/chisel/releases/tag/v1.4.0 \ No newline at end of file From 09d869916b1ec61f8573dfdb3168e3fee965ae27 Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Wed, 18 Feb 2026 16:44:15 +0100 Subject: [PATCH 07/10] fix: missing block closure --- docs/reference/chisel-releases/chisel.yaml.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index 10db6b7..e2768ac 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -65,6 +65,8 @@ that support said `format`. | `26.04 `_ | x | x | >= `v1.4.0 `_| +-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +``` + (chisel_yaml_format_spec_archives)= ### `archives` From 1f145d92c946bda338e7dbb37fd479c5077e9f7c Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Wed, 18 Feb 2026 16:44:54 +0100 Subject: [PATCH 08/10] Update docs/reference/chisel-releases/slice-definitions.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: Cristovao Cordeiro --- docs/reference/chisel-releases/slice-definitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index ef4de4b..af80f74 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -92,7 +92,7 @@ alongside their `essential`-specific properties. | `arch` | `string` or `array` | Optional | `amd64`, `arm64`, `armhf`, `i386`, `ppc64el`, `riscv64`, `s390x` | Used to specify the package architectures an _essential_ dependency should be -installed for. This field can take a single architecture string or a list, as its +installed for. This field can take a single architecture string or a list as its value. In the following example, `hello_copyright` will be installed for every installation From e3e27775513b0ad715670621669db70ab740bbd3 Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Wed, 18 Feb 2026 16:49:04 +0100 Subject: [PATCH 09/10] Update docs/reference/chisel-releases/slice-definitions.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: Cristovao Cordeiro --- docs/reference/chisel-releases/slice-definitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index af80f74..b453f14 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -82,7 +82,7 @@ but applicable for every slice within the package. | ----------- | -------- | -------- | | `essential` | `object` | Optional | -A map of slices, in their full name (e.g. `hello_copyright`), +A map of slices by their full names (e.g. `hello_copyright`), alongside their `essential`-specific properties. #### `essential..arch` From 6f2837bf43c27432460e44fbddb526b02174f06b Mon Sep 17 00:00:00 2001 From: Cristovao Cordeiro Date: Wed, 18 Feb 2026 18:31:42 +0100 Subject: [PATCH 10/10] chore: rename table header --- docs/reference/chisel-releases/slice-definitions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index b453f14..32d2572 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -82,7 +82,7 @@ but applicable for every slice within the package. | ----------- | -------- | -------- | | `essential` | `object` | Optional | -A map of slices by their full names (e.g. `hello_copyright`), +A map of slices, in their full name (e.g. `hello_copyright`), alongside their `essential`-specific properties. #### `essential..arch` @@ -92,7 +92,7 @@ alongside their `essential`-specific properties. | `arch` | `string` or `array` | Optional | `amd64`, `arm64`, `armhf`, `i386`, `ppc64el`, `riscv64`, `s390x` | Used to specify the package architectures an _essential_ dependency should be -installed for. This field can take a single architecture string or a list as its +installed for. This field can take a single architecture string or a list, as its value. In the following example, `hello_copyright` will be installed for every installation @@ -468,9 +468,9 @@ In the following example, Chisel creates the `/var/lib/chisel` directory with ### `slices..contents..prefer` -| Field | Type | Required | Format compatibility | +| Field | Type | Required | Introduced in format | | ---------- | -------- | -------- | -------- | -| `prefer` | `string` | Optional | >= {ref}`v2` | +| `prefer` | `string` | Optional | {ref}`v2` | Used to resolve a path conflict across multiple packages. @@ -575,9 +575,9 @@ and the files inside are not present in the final root file system. ### `slices..hint` -| Field | Type | Required | Format compatibility | +| Field | Type | Required | Introduced in format | | ------ | -------- | -------- | -------------------- | -| `hint` | `string` | Optional | >= {ref}`v3` | +| `hint` | `string` | Optional | {ref}`v3` | Provides a concise and unopinionated discriminator to help the user select slices. It focuses on describing the *subset* of contents coming from this slice. It does