From 4776eedc264c1d845e21640a038854e7da17566a Mon Sep 17 00:00:00 2001 From: Alberto Carretero Date: Tue, 9 Sep 2025 12:08:29 +0200 Subject: [PATCH 1/3] feat: add maintenance to the reference --- docs/reference/chisel-releases/chisel.yaml.md | 51 +++++++++++++++++++ docs/reference/cmd/cut.md | 3 ++ 2 files changed, 54 insertions(+) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index 3ee788b..0ff2e52 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -38,6 +38,57 @@ New formats are typically introduced with new _chisel-releases_ and may introduce disruptive changes to the previous formats. ``` +(chisel_yaml_format_spec_maintenance)= + +### `maintenance` + +| Field | Type | Required | +| ------------- | -------- | -------- | +| `maintenance` | `object` | Required | + +Includes the dates that mark the different stages of Canonical's support for a +release. In Chisel we say that a release is "unmaintained" after its +`end-of-life`, and "unstable" before its `standard` date. + +Chisel by default will only cut the releases which are officially maintained. +To use "unstable" or "unmaintained" releases see the reference for the +{ref}`cut command`. + +For more information about Ubuntu's release cycle see +https://ubuntu.com/about/release-cycle. + +### `maintenance.standard` + +| Field | Type | Required | +| ---------- | ------------------- | -------- | +| `standard` | `date (YYYY-MM-DD)` | Required | + +Marks the start of standard support. + +### `maintenance.expanded` + +| Field | Type | Required | +| ---------- | ------------------- | --------- | +| `expanded` | `date (YYYY-MM-DD)` | Optional | + +Marks the start of expanded support (only valid for LTS releases). + +### `maintenance.legacy` + +| Field | Type | Required | +| -------- | ------------------- | --------- | +| `legacy` | `date (YYYY-MM-DD)` | Optional | + +Marks the start of legacy support (only valid for LTS releases). + +### `maintenance.end-of-life` + +| Field | Type | Required | +| ------------- | ------------------- | -------- | +| `end-of-life` | `date (YYYY-MM-DD)` | Required | + +After `end-of-life` the release is no longer officially maintained by +Canonical. (chisel_yaml_format_spec_archives)= diff --git a/docs/reference/cmd/cut.md b/docs/reference/cmd/cut.md index 48e2f47..294fbd9 100644 --- a/docs/reference/cmd/cut.md +++ b/docs/reference/cmd/cut.md @@ -15,6 +15,9 @@ current host, unless the `--release` option is used. - `--release` is a {{chisel_releases_repo}} branch or local directory (e.g. ubuntu-22.04). - `--root` is the path for the resulting root file system. - `--arch` is used to specify the desired package architecture. +- `--ignore` is used to work with "unstable" or "unmaintained" releases (see + {ref}`here`). The valid values are + "unstable" or "unmaintained" respectively. From 4227e631413e246715a430f54534988adaa085fc Mon Sep 17 00:00:00 2001 From: Alberto Carretero Date: Wed, 10 Sep 2025 12:36:28 +0200 Subject: [PATCH 2/3] address review --- docs/reference/chisel-releases/chisel.yaml.md | 104 +++++++++--------- docs/reference/cmd/cut.md | 6 +- 2 files changed, 55 insertions(+), 55 deletions(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index 0ff2e52..360fa1f 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -38,58 +38,6 @@ New formats are typically introduced with new _chisel-releases_ and may introduce disruptive changes to the previous formats. ``` -(chisel_yaml_format_spec_maintenance)= - -### `maintenance` - -| Field | Type | Required | -| ------------- | -------- | -------- | -| `maintenance` | `object` | Required | - -Includes the dates that mark the different stages of Canonical's support for a -release. In Chisel we say that a release is "unmaintained" after its -`end-of-life`, and "unstable" before its `standard` date. - -Chisel by default will only cut the releases which are officially maintained. -To use "unstable" or "unmaintained" releases see the reference for the -{ref}`cut command`. - -For more information about Ubuntu's release cycle see -https://ubuntu.com/about/release-cycle. - -### `maintenance.standard` - -| Field | Type | Required | -| ---------- | ------------------- | -------- | -| `standard` | `date (YYYY-MM-DD)` | Required | - -Marks the start of standard support. - -### `maintenance.expanded` - -| Field | Type | Required | -| ---------- | ------------------- | --------- | -| `expanded` | `date (YYYY-MM-DD)` | Optional | - -Marks the start of expanded support (only valid for LTS releases). - -### `maintenance.legacy` - -| Field | Type | Required | -| -------- | ------------------- | --------- | -| `legacy` | `date (YYYY-MM-DD)` | Optional | - -Marks the start of legacy support (only valid for LTS releases). - -### `maintenance.end-of-life` - -| Field | Type | Required | -| ------------- | ------------------- | -------- | -| `end-of-life` | `date (YYYY-MM-DD)` | Required | - -After `end-of-life` the release is no longer officially maintained by -Canonical. - (chisel_yaml_format_spec_archives)= ### `archives` @@ -272,6 +220,58 @@ Although not enforced, the following `priority` values are suggested when ``` +(chisel_yaml_format_spec_maintenance)= + +### `maintenance` + +| Field | Type | Required | +| ------------- | -------- | -------- | +| `maintenance` | `object` | Required | + +Includes the dates that mark the different stages of Canonical's support for a +release. In Chisel we say that a release is "unmaintained" after its +`end-of-life`, and "unstable" before its `standard` date. + +Chisel by default will only cut the releases which are officially maintained. +To use "unstable" or "unmaintained" releases see the reference for the +{ref}`cut command`. + +For more information about Ubuntu's release cycle see +https://ubuntu.com/about/release-cycle. + +### `maintenance.standard` + +| Field | Type | Required | +| ---------- | ------------------- | -------- | +| `standard` | `date (YYYY-MM-DD)` | Required | + +Marks the start of standard support. + +### `maintenance.expanded` + +| Field | Type | Required | +| ---------- | ------------------- | --------- | +| `expanded` | `date (YYYY-MM-DD)` | Optional | + +Marks the start of expanded support (only valid for LTS releases). + +### `maintenance.legacy` + +| Field | Type | Required | +| -------- | ------------------- | --------- | +| `legacy` | `date (YYYY-MM-DD)` | Optional | + +Marks the start of legacy support (only valid for LTS releases). + +### `maintenance.end-of-life` + +| Field | Type | Required | +| ------------- | ------------------- | -------- | +| `end-of-life` | `date (YYYY-MM-DD)` | Required | + +After `end-of-life` the release is no longer officially maintained by +Canonical. + (chisel_yaml_format_spec_public_keys)= ### `public-keys` diff --git a/docs/reference/cmd/cut.md b/docs/reference/cmd/cut.md index 294fbd9..c30b989 100644 --- a/docs/reference/cmd/cut.md +++ b/docs/reference/cmd/cut.md @@ -15,9 +15,9 @@ current host, unless the `--release` option is used. - `--release` is a {{chisel_releases_repo}} branch or local directory (e.g. ubuntu-22.04). - `--root` is the path for the resulting root file system. - `--arch` is used to specify the desired package architecture. -- `--ignore` is used to work with "unstable" or "unmaintained" releases (see - {ref}`here`). The valid values are - "unstable" or "unmaintained" respectively. +- `--ignore` is used to allow Chisel to work with "unstable" or "unmaintained" + releases (see {ref}`here`). The valid + values are "unstable" or "unmaintained", respectively. From 0f81d432340414d8a3569d20396f1b1ec442cb90 Mon Sep 17 00:00:00 2001 From: Alberto Carretero Date: Mon, 15 Sep 2025 13:30:04 +0200 Subject: [PATCH 3/3] add version column in all attributed --- docs/reference/chisel-releases/chisel.yaml.md | 98 +++++++++---------- 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index 360fa1f..b56f38d 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` | +| `format` | `string` | Required | `v1`, `v2` | Used to define the supported schemas for the {ref}`chisel-releases_ref`. For example: @@ -42,9 +42,9 @@ introduce disruptive changes to the previous formats. ### `archives` -| Field | Type | Required | -| ---------- | -------- | -------- | -| `archives` | `object` | Required | +| Field | Type | Required | Compatibility | +| ---------- | -------- | -------- | ------------- | +| `archives` | `object` | Required | >= `v1` | Tells Chisel which Ubuntu archives to fetch packages from. @@ -80,9 +80,9 @@ otherwise, the archive point to the Ubuntu Pro archives listed ### `archives..default` -| Field | Type | Required | Supported values | -| --------- | --------- | --------------------------------------------------------------------------------------------------- | ---------------- | -| `default` | `boolean` | Required with multiple archives, if no {ref}`priorities` | `true`, `false` | +| Field | Type | Required | Supported values | Compatibility | +| --------- | --------- | --------------------------------------------------------------------------------------------------- | ---------------- | ------------- | +| `default` | `boolean` | Required with multiple archives, if no {ref}`priorities` | `true`, `false` | `v1` | If `default` is `true`, Chisel fetches packages from this archive, unless otherwise specified by the field {ref}`"archive"` @@ -101,9 +101,9 @@ so use {ref}`chisel_yaml_format_spec_archives_priority` instead. ### `archives..version` -| Field | Type | Required | Supported values | -| --------- | -------- | -------- | ------------------------------------------------------- | -| `version` | `string` | Required | Ubuntu release in `xx.yy` format e.g. 22.04, 24.04 etc. | +| Field | Type | Required | Supported values | Compatibility | +| --------- | -------- | -------- | ------------------------------------------------------- | ------------- | +| `version` | `string` | Required | Ubuntu release in `xx.yy` format e.g. 22.04, 24.04 etc. | >= `v1` | Indicates the Ubuntu release this archive should fetch the packages for. This value is currently only used for logging, and does not change @@ -114,9 +114,9 @@ the archive behaviour. ### `archives..suites` -| Field | Type | Required | Supported values | -| -------- | --------------- | -------- | ------------------------------------------------------------- | -| `suites` | `array` | Required | Ubuntu archive suite names e.g. `jammy`, `noble-updates` etc. | +| Field | Type | Required | Supported values | Compatibility | +| -------- | --------------- | -------- | ------------------------------------------------------------- | ------------- | +| `suites` | `array` | Required | Ubuntu archive suite names e.g. `jammy`, `noble-updates` etc. | >= `v1` | Lists the archive suites to fetch packages from. Read more about suites in the [Ubuntu packaging @@ -127,9 +127,9 @@ guide](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/latest ### `archives..components` -| Field | Type | Required | Supported values | -| ------------ | --------------- | -------- | -------------------------------------------------- | -| `components` | `array` | Required | Suite component names e.g. `main`, `universe` etc. | +| Field | Type | Required | Supported values | Compatibility | +| ------------ | --------------- | -------- | -------------------------------------------------- | ------------- | +| `components` | `array` | Required | Suite component names e.g. `main`, `universe` etc. | >= `v1` | Lists the components of the archive suites to fetch packages from. Read more about components in the [Ubuntu packaging @@ -143,9 +143,9 @@ locate packages. ### `archives..public-keys` -| Field | Type | Required | Supported values | -| ------------- | --------------- | -------- | --------------------------------------------------------------------------- | -| `public-keys` | `array` | Required | List of key names, as defined in {ref}`chisel_yaml_format_spec_public_keys` | +| Field | Type | Required | Supported values | Compatibility | +| ------------- | --------------- | -------- | --------------------------------------------------------------------------- | ------------- | +| `public-keys` | `array` | Required | List of key names, as defined in {ref}`chisel_yaml_format_spec_public_keys` | >= `v1` | Lists the names of the OpenPGP public keys needed to verify the archive's `InRelease` file signatures. These key names must be defined in @@ -156,9 +156,9 @@ file signatures. These key names must be defined in ### `archives..priority` -| Field | Type | Required | Supported values | -| ---------- | --------- | ------------------------------------------------ | ---------------------------------- | -| `priority` | `integer` | Required with multiple archives, if no `default` | Any integer between -1000 and 1000 | +| Field | Type | Required | Supported values | Compatibility | +| ---------- | --------- | ------------------------------------------------ | ---------------------------------- | ------------- | +| `priority` | `integer` | Required with multiple archives, if no `default` | Any integer between -1000 and 1000 | >= `v1` | Describes the priority of an archive compared to other archives. It is used to support multiple archives in Chisel. If a package is @@ -175,9 +175,9 @@ Note that: ### `archives..pro` -| Field | Type | Required | Supported values | -| ----- | -------- | -------- | ------------------------------------------------ | -| `pro` | `string` | Optional | `fips`, `fips-updates`, `esm-apps`, `esm-infra`. | +| Field | Type | Required | Supported values | Compatibility | +| ----- | -------- | -------- | ------------------------------------------------ | ------------- | +| `pro` | `string` | Optional | `fips`, `fips-updates`, `esm-apps`, `esm-infra`. | >= `v1` | Specifies the [Ubuntu Pro](https://ubuntu.com/pro) archive to fetch and install packages from. @@ -224,9 +224,9 @@ Although not enforced, the following `priority` values are suggested when ### `maintenance` -| Field | Type | Required | -| ------------- | -------- | -------- | -| `maintenance` | `object` | Required | +| Field | Type | Required | Compatibility | +| ------------- | -------- | -------- | ------------- | +| `maintenance` | `object` | Required | >= `v2` | Includes the dates that mark the different stages of Canonical's support for a release. In Chisel we say that a release is "unmaintained" after its @@ -241,33 +241,33 @@ https://ubuntu.com/about/release-cycle. ### `maintenance.standard` -| Field | Type | Required | -| ---------- | ------------------- | -------- | -| `standard` | `date (YYYY-MM-DD)` | Required | +| Field | Type | Required | Compatibility | +| ---------- | ------------------- | -------- | ------------- | +| `standard` | `date (YYYY-MM-DD)` | Required | >= `v2` | Marks the start of standard support. ### `maintenance.expanded` -| Field | Type | Required | -| ---------- | ------------------- | --------- | -| `expanded` | `date (YYYY-MM-DD)` | Optional | +| Field | Type | Required | Compatibility | +| ---------- | ------------------- | --------- | ------------- | +| `expanded` | `date (YYYY-MM-DD)` | Optional | >= `v2` | Marks the start of expanded support (only valid for LTS releases). ### `maintenance.legacy` -| Field | Type | Required | -| -------- | ------------------- | --------- | -| `legacy` | `date (YYYY-MM-DD)` | Optional | +| Field | Type | Required | Compatibility | +| -------- | ------------------- | --------- | ------------- | +| `legacy` | `date (YYYY-MM-DD)` | Optional | >= `v2` | Marks the start of legacy support (only valid for LTS releases). ### `maintenance.end-of-life` -| Field | Type | Required | -| ------------- | ------------------- | -------- | -| `end-of-life` | `date (YYYY-MM-DD)` | Required | +| Field | Type | Required | Compatibility | +| ------------- | ------------------- | -------- | ------------- | +| `end-of-life` | `date (YYYY-MM-DD)` | Required | >= `v2` | After `end-of-life` the release is no longer officially maintained by Canonical. @@ -276,9 +276,9 @@ Canonical. ### `public-keys` -| Field | Type | Required | -| ------------- | -------- | -------- | -| `public-keys` | `object` | Required | +| Field | Type | Required | Compatibility | +| ------------- | -------- | -------- | ------------- | +| `public-keys` | `object` | Required | >= `v1` | The top-level `public-keys` field is used to define OpenPGP public keys that are needed to verify the `InRelease` file signatures of the @@ -306,9 +306,9 @@ The key names are then referenced in ### `public-keys..id` -| Field | Type | Required | -| ----- | -------- | -------- | -| `id` | `string` | Required | +| Field | Type | Required | Compatibility | +| ----- | -------- | -------- | ------------- | +| `id` | `string` | Required | >= `v1` | The `id` field specifies the OpenPGP public key fingerprint in capital hex e.g. `871920D1991BC93C`. It must be 16 chars long and must match the decoded @@ -319,9 +319,9 @@ fingerprint in {ref}`chisel_yaml_format_spec_public_keys_armor`. ### `public-keys..armor` -| Field | Type | Required | -| ------- | -------- | -------- | -| `armor` | `string` | Required | +| Field | Type | Required | Compatibility | +| ------- | -------- | -------- | ------------- | +| `armor` | `string` | Required | >= `v1` | The `armor` field contains the multi-line armored ASCII data of OpenPGP public key.