From ea543f96a5daa611897d323ece8cbe695cc72325 Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 12:46:39 +0200 Subject: [PATCH 01/15] Remove 'faq' from the documentation TOC Signed-off-by: barbaravalera --- docs/explanation/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 48e627b..756bebb 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -9,7 +9,6 @@ Chisel was created to build a minimal, secure Ubuntu root file systems. :maxdepth: 1 mode-of-operation -faq ``` ## Package slices Slices are defined via slice definition files and follow naming conventions. From 412f3b38d7aac6533e2053096e7e542e0af501ab Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 12:47:16 +0200 Subject: [PATCH 02/15] Delete docs/explanation/faq.md Signed-off-by: barbaravalera --- docs/explanation/faq.md | 67 ----------------------------------------- 1 file changed, 67 deletions(-) delete mode 100644 docs/explanation/faq.md diff --git a/docs/explanation/faq.md b/docs/explanation/faq.md deleted file mode 100644 index 4b66b80..0000000 --- a/docs/explanation/faq.md +++ /dev/null @@ -1,67 +0,0 @@ -(chise_faq)= - -# FAQ - -This page lists some known limitations and frequently asked questions. - - -(faq_arbitrary_package_names)= - -## Is it possible to use arbitrary package names? - -No, package names must be the same as the package names in the archive, so that -there's a single namespace to remember and respect. - - -(faq_available_ubuntu_versions)= - -## Which Ubuntu versions have package slices? - -The slice definitions are located at the {{chisel_releases_repo}}. The -`ubuntu-XX.YY` branches in that repository contain the slice definitions for -the corresponding Ubuntu releases. - -If you find a specific release missing, let the maintainers know by [creating a -new issue] in the {{chisel_releases_repo}}. - - -(faq_non-ubuntu_archives)= - -## Is it possible to use non-Ubuntu archives? - -No. The supported archives are described at -{ref}`chisel_yaml_format_spec_archives`. - - -(faq_ppa)= - -## Is it possible to use PPAs? - -Not at the moment. - - -(faq_file_ownership_preserved)= - -## Is file ownership preserved? - -No, Chisel does not yet preserve the owner UID:GID of files extracted from -packages. The owner of the extracted files is the current user. - - -(faq_reproducible_output)= - -## Does Chisel support reproducible rootfs outputs? - -Chisel always fetches the latest version of a package from the archives. Thus, -the root file systems Chisel produces in subsequent executions may not be -identical if a package has changed in the meantime. - -Chisel also does not support pinning package versions. - -Related: [Issue 154]. - - - - -[creating a new issue]: https://github.com/canonical/chisel-releases/issues/new -[Issue 154]: https://github.com/canonical/chisel/issues/154 From e0f6cd6bd970f17ae53ac583c1bc8aff95542ccb Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 12:49:12 +0200 Subject: [PATCH 03/15] Update note on Ubuntu package fetching restrictions Clarified that PPAs are not supported for package fetching. Signed-off-by: barbaravalera --- docs/reference/chisel-releases/chisel.yaml.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index e2768ac..61e4ba3 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -79,7 +79,7 @@ Tells Chisel which Ubuntu archives to fetch packages from. ```{note} Chisel only supports fetching packages from the official Ubuntu archives, -including ESM. +including ESM. The use of PPAs is excluded at the moment. ``` For example: From fc99edb644442048750c6a22bf7c35ee068c7274 Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 12:50:56 +0200 Subject: [PATCH 04/15] Update slice-definitions.md for package naming rules Clarify package name requirements and archive definitions. Signed-off-by: barbaravalera --- docs/reference/chisel-releases/slice-definitions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index 32d2572..18643c2 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -34,6 +34,10 @@ Although the `hello.yaml` file can be placed in a sub-directory of `slices/` e.g Indicates the package name. It must follow the [Debian policy for package name](https://www.debian.org/doc/debian-policy/ch-binary.html#the-package-name). +The use of arbitrary package names is not allowed; the names must be the +same as the package names in the archive to maintain a single namespace +to remember and respect. + As indicated above, the value must also match the YAML file basename. For example: @@ -56,6 +60,8 @@ fetched from. If specified, Chisel fetches this package from that archive despit {ref}`chisel_yaml_format_spec_archives_priority` settings in {ref}`chisel_yaml_ref`. +The supported archives are described at {ref}`chisel_yaml_format_spec_archives`. + The archive name must be defined in {ref}`chisel_yaml_format_spec_archives`. For example: From f14a3780a27e7b02ead02f5e61e5fa51ec28d7c0 Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 12:51:48 +0200 Subject: [PATCH 05/15] Update mode-of-operation.md Signed-off-by: barbaravalera --- docs/explanation/mode-of-operation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/explanation/mode-of-operation.md b/docs/explanation/mode-of-operation.md index 6fa067e..90e39b6 100644 --- a/docs/explanation/mode-of-operation.md +++ b/docs/explanation/mode-of-operation.md @@ -69,7 +69,9 @@ the corresponding package tarballs. Chisel groups and merges all slice definitions per package. Then, for every package, it extracts the **specified slices' paths** into -the provided root file system. +the provided root file system. Files ownership (UID:GID) is not +preserved during this process. The owner of the extracted files +is the current user. From a39b548ff3c4b6069369bc6998e89886b5a125e3 Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 13:08:34 +0200 Subject: [PATCH 06/15] Update index.md with issue creation link Added a link to create a new issue for missing releases. Signed-off-by: barbaravalera --- docs/reference/chisel-releases/index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/reference/chisel-releases/index.md b/docs/reference/chisel-releases/index.md index 15eacea..36f6f99 100644 --- a/docs/reference/chisel-releases/index.md +++ b/docs/reference/chisel-releases/index.md @@ -11,6 +11,9 @@ named `chisel.yaml` form what is called a _chisel-release_. The {{chisel_releases_repo}} contains a number of branches for various _chisel-releases_, matching the corresponding Ubuntu releases. +If you find a specific release missing, let the maintainers know by [creating a +new issue] in the {{chisel_releases_repo}}. + A _chisel-release_ is simply a directory with the following structure: @@ -25,6 +28,8 @@ A _chisel-release_ is simply a directory with the following structure: The following pages provide more details on: ```{toctree} + +[creating a new issue]: https://github.com/canonical/chisel-releases/issues/new :maxdepth: 1 chisel.yaml From 34da458b94db899c4a38f8ec3953e0b045ea967f Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 13:11:08 +0200 Subject: [PATCH 07/15] Fix issue link in chisel-releases documentation Updated the link for creating a new issue in the chisel-releases repository. Signed-off-by: barbaravalera --- docs/reference/chisel-releases/index.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/reference/chisel-releases/index.md b/docs/reference/chisel-releases/index.md index 36f6f99..f672ce6 100644 --- a/docs/reference/chisel-releases/index.md +++ b/docs/reference/chisel-releases/index.md @@ -12,7 +12,7 @@ named `chisel.yaml` form what is called a _chisel-release_. The {{chisel_releases_repo}} contains a number of branches for various _chisel-releases_, matching the corresponding Ubuntu releases. If you find a specific release missing, let the maintainers know by [creating a -new issue] in the {{chisel_releases_repo}}. +new issue](https://github.com/canonical/chisel-releases/issues/new) in the {{chisel_releases_repo}}. A _chisel-release_ is simply a directory with the following structure: @@ -29,9 +29,6 @@ The following pages provide more details on: ```{toctree} -[creating a new issue]: https://github.com/canonical/chisel-releases/issues/new -:maxdepth: 1 - chisel.yaml slice-definitions ``` From 542695ec2115ce442b2cc0989cd08f7169e90891 Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 13:46:28 +0200 Subject: [PATCH 08/15] Update slice-definitions.md Signed-off-by: barbaravalera --- docs/reference/chisel-releases/slice-definitions.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index 18643c2..2a93c3e 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -45,6 +45,11 @@ For example: package: hello ``` +Chisel does not support pinning package versions. Chisel always fetches +the latest version of a package from the archives. Thus,the root file +systems Chisel produces in subsequent executions may not be identical if +a package has changed in the meantime. + (slice_definitions_format_archive)= ### `archive` From 22bb5ee5ff1832b7ca248516d55aa5b62f5d7811 Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Mon, 18 May 2026 13:47:20 +0200 Subject: [PATCH 09/15] Correct package versioning explanation in documentation Fix formatting and clarify package versioning behavior. Signed-off-by: barbaravalera --- 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 2a93c3e..760b63d 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -46,7 +46,7 @@ package: hello ``` Chisel does not support pinning package versions. Chisel always fetches -the latest version of a package from the archives. Thus,the root file +the latest version of a package from the archives. Thus, the root file systems Chisel produces in subsequent executions may not be identical if a package has changed in the meantime. From 0eb1f5ef5bb357988a6effdc3d7671e39d11dbad Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Tue, 19 May 2026 09:22:37 +0200 Subject: [PATCH 10/15] Update documentation for Chisel releases Signed-off-by: barbaravalera --- docs/reference/chisel-releases/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/chisel-releases/index.md b/docs/reference/chisel-releases/index.md index f672ce6..09b1f6b 100644 --- a/docs/reference/chisel-releases/index.md +++ b/docs/reference/chisel-releases/index.md @@ -28,6 +28,7 @@ A _chisel-release_ is simply a directory with the following structure: The following pages provide more details on: ```{toctree} +:maxdepth: 1 chisel.yaml slice-definitions From ba6fff6efdf14e6bc5dab2b6f82199fef3f0b0bc Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Tue, 19 May 2026 09:33:49 +0200 Subject: [PATCH 11/15] Correct formatting in chisel-releases documentation Fixed formatting issues in the documentation. Signed-off-by: barbaravalera --- docs/reference/chisel-releases/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/reference/chisel-releases/index.md b/docs/reference/chisel-releases/index.md index 09b1f6b..e3aeae0 100644 --- a/docs/reference/chisel-releases/index.md +++ b/docs/reference/chisel-releases/index.md @@ -12,7 +12,7 @@ named `chisel.yaml` form what is called a _chisel-release_. The {{chisel_releases_repo}} contains a number of branches for various _chisel-releases_, matching the corresponding Ubuntu releases. If you find a specific release missing, let the maintainers know by [creating a -new issue](https://github.com/canonical/chisel-releases/issues/new) in the {{chisel_releases_repo}}. +new issue] in the {{chisel_releases_repo}}. A _chisel-release_ is simply a directory with the following structure: @@ -33,3 +33,6 @@ The following pages provide more details on: chisel.yaml slice-definitions ``` + +[creating a +new issue]: https://github.com/canonical/chisel-releases/issues/new From 1c27ad5e8f3924e962f81728096a73cdd8fe20aa Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Thu, 21 May 2026 11:34:54 +0200 Subject: [PATCH 12/15] Update docs/reference/chisel-releases/chisel.yaml.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: barbaravalera --- docs/reference/chisel-releases/chisel.yaml.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index 61e4ba3..d0cbd88 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -79,7 +79,7 @@ Tells Chisel which Ubuntu archives to fetch packages from. ```{note} Chisel only supports fetching packages from the official Ubuntu archives, -including ESM. The use of PPAs is excluded at the moment. +including ESM. The use of PPAs is not supported at the moment. ``` For example: From e4476c17ea0ce546f38324adc69b838b5e671cba Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Thu, 21 May 2026 11:35:58 +0200 Subject: [PATCH 13/15] Update docs/reference/chisel-releases/slice-definitions.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: barbaravalera --- docs/reference/chisel-releases/slice-definitions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index 760b63d..e7a4483 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -65,7 +65,6 @@ fetched from. If specified, Chisel fetches this package from that archive despit {ref}`chisel_yaml_format_spec_archives_priority` settings in {ref}`chisel_yaml_ref`. -The supported archives are described at {ref}`chisel_yaml_format_spec_archives`. The archive name must be defined in {ref}`chisel_yaml_format_spec_archives`. For example: From 629bb7117ec962e5513136bc3068522a21968e0a Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Thu, 21 May 2026 11:36:10 +0200 Subject: [PATCH 14/15] Update docs/reference/chisel-releases/slice-definitions.md Co-authored-by: Anna Sancho Vaquer Signed-off-by: barbaravalera --- docs/reference/chisel-releases/slice-definitions.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index e7a4483..2b9417f 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -38,17 +38,16 @@ The use of arbitrary package names is not allowed; the names must be the same as the package names in the archive to maintain a single namespace to remember and respect. +Chisel does not support pinning package versions. Chisel always fetches +the latest version of a package from the archives. Thus, the root file +systems Chisel produces in subsequent executions may not be identical if +a package has changed in the meantime. + As indicated above, the value must also match the YAML file basename. For example: ```yaml package: hello -``` - -Chisel does not support pinning package versions. Chisel always fetches -the latest version of a package from the archives. Thus, the root file -systems Chisel produces in subsequent executions may not be identical if -a package has changed in the meantime. (slice_definitions_format_archive)= From 756d1a41d5b54168a644383109dee27383f86842 Mon Sep 17 00:00:00 2001 From: barbaravalera Date: Thu, 21 May 2026 11:47:55 +0200 Subject: [PATCH 15/15] Fix formatting in slice-definitions.md Signed-off-by: barbaravalera --- 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 2b9417f..811cb13 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -48,7 +48,7 @@ For example: ```yaml package: hello - +``` (slice_definitions_format_archive)= ### `archive`