feat: add a migration branch for v1.4.0

docs/.custom_wordlist.txt

@@ -21,6 +21,7 @@ armor
 armored
 basename
 behavior
+binutils
 chiseled
 conffiles
 config
@@ -33,6 +34,7 @@ fips
 http
 https
 initialize
+jaotc
 jsonwall
 libs
 linters
@@ -48,6 +50,9 @@ subcommand
 subcommands
 symlink
 symlinks
+timezones
 ubuntu
+unopinionated
 whitespace
 yaml
+Canonical's

docs/.github/.jira_sync_config.yaml

@@ -0,0 +1,59 @@
+settings:
+    # Jira project key to create the issue in
+  jira_project_key: "ROCKS"
+
+  # Dictionary mapping GitHub issue status to Jira issue status
+  status_mapping:
+    opened: Untriaged
+    closed: done
+    # (Optional) Use different status for GitHub issues closed as not planned (instead of closed as
+    # completed)
+    # https://github.blog/changelog/2022-03-10-the-new-github-issues-march-10th-update/#%F0%9F%95%B5%F0%9F%8F%BD%E2%99%80%EF%B8%8F-issue-closed-reasons
+    # If not specified, `closed` status will be used.
+    not_planned: rejected
+
+  # (Optional) Jira project components that should be attached to the created issue
+  # Component names are case-sensitive
+  components:
+
+  # (Optional) GitHub labels. Only issues with one of those labels will be synchronized.
+  # If not specified, all issues will be synchronized
+  labels:
+
+  # (Optional) (Default: false) Add a new comment in GitHub with a link to Jira created issue
+  add_gh_comment: false
+
+  # (Optional) (Default: false) Add a 'synced-to-jira' label to newly created issues once a
+  # corresponding ticket is successfully created in Jira.
+  # This label serves as confirmation that the issue sync process was completed successfully.
+  add_gh_synced_label: false
+
+  # (Optional) (Default: true) Synchronize issue description from GitHub to Jira
+  sync_description: true
+
+  # (Optional) (Default: true) Synchronize comments from GitHub to Jira
+  sync_comments: true
+
+  # (Optional) (Default: None) Parent Epic key to link the issue to
+  epic_key: "ROCKS-2724"
+
+  # (Optional) Dictionary mapping GitHub issue labels to Jira issue types. 
+  # If label on the issue is not in specified list, this issue will be created as a Bug
+  label_mapping:
+    enhancement: Task
+
+  # (Optional) JIRA issue's summary
+  # This field can be used to customize the JIRA issue's summary (title).
+  # The value of the field will be passed to the python
+  # format() method to generate the JIRA summary. The GH issue
+  # variable will be captured in the format() method so that users can
+  # use GH issue attribute's values to build the JIRA summary.
+  # See GH issue definition :
+  # https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28
+  #
+  # Examples:
+  # to use fixed title "github issue": "github issue"
+  # to use GH issue title: "{issue.title}"
+  # to add prefix "[GitHub]" : "[GitHub] {issue.title}"
+  # to add user in the title (between square brackets): "[{issue.user.login}] {issue.title}"
+  summary: "[GitHub] {issue.title}"

docs/_static/js/overwrite_links.js

@@ -0,0 +1,38 @@
+ // Replace oldDomain with newDomain
+ const oldDomain = 'canonical-chisel-migration.readthedocs-hosted.com';
+ const newDomain = 'ubuntu.com/chisel/docs';
+
+ function escapeRegExp(value) {
+     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ }
+
+ function overwriteMatchingAnchorUrls(container) {
+     if (!container) return;
+
+     const anchors = container.querySelectorAll('a[href], link[href]');
+     const oldDomainRegex = new RegExp(escapeRegExp(oldDomain), 'g');
+
+     anchors.forEach(anchor => {
+         anchor.href = anchor.href.replace(oldDomainRegex, newDomain);
+     });
+ }
+
+ overwriteMatchingAnchorUrls(document.querySelector('header'));
+
+ // Use a MutationObserver to wait for the RTD flyout element to appear in the DOM
+ const observer = new MutationObserver(function(mutations, obs) {
+
+     const rtdFlyout = document.querySelector('readthedocs-flyout');
+     if (!rtdFlyout) return;
+
+     obs.disconnect();
+
+     rtdFlyout.addEventListener('click', function() {
+         const shadowRoot = rtdFlyout.shadowRoot;
+         if (!shadowRoot) return;
+
+         overwriteMatchingAnchorUrls(shadowRoot);
+     });
+ });
+
+ observer.observe(document.body, { childList: true, subtree: true });

docs/conf.py

@@ -31,7 +31,9 @@
 # Sidebar documentation title; best kept reasonably short
 #
 # TODO: To include a version number, add it here (hardcoded or automated).
-#
+
+version = f"{os.environ.get('READTHEDOCS_VERSION', 'local')}"
+
 # TODO: To disable the title, set to an empty string.
 
 html_title = project + " documentation"
@@ -70,7 +72,7 @@
 # NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph
 #       and is used by social media platforms; see https://ogp.me/
 
-ogp_site_url = "https://documentation.ubuntu.com/chisel/"
+ogp_site_url = f"https://ubuntu.com/chisel/docs/{version}/"
 
 
 # Preview name of the documentation website
@@ -176,29 +178,31 @@
 # TODO: If your documentation is hosted on https://docs.ubuntu.com/,
 #       uncomment and update as needed.
 
-slug = "chisel"
+slug = 'chisel/docs' # Or '<ecosystem>/<product>/docs'
 
 #######################
 # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/
 #######################
 
 # Use RTD canonical URL to ensure duplicate pages have a specific canonical URL
 
-html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
+html_baseurl = f"https://ubuntu.com/chisel/docs/{version}/"
 
 # URL scheme. Add language and version scheme elements.
 # When configured with RTD variables, check for RTD environment so manual runs succeed:
 
 if 'READTHEDOCS_VERSION' in os.environ:
     version = os.environ["READTHEDOCS_VERSION"]
-    sitemap_url_scheme = '{version}{link}'
+    sitemap_url_scheme = '{link}'
 else:
     sitemap_url_scheme = 'MANUAL/{link}'
 
 # Include `lastmod` dates in the sitemap:
 
 sitemap_show_lastmod = True
 
+sitemap_filename = "doc-sitemap.xml"
+
 # Exclude generated pages from the sitemap:
 
 sitemap_excludes = [
@@ -313,6 +317,7 @@
 
 html_js_files = [
     'bundle.js',
+    "js/overwrite_links.js",
 ]
 
 
@@ -377,4 +382,3 @@
 def setup(app):
     app.add_css_file("tasklist.css")
     app.add_js_file("tasklist.js")  #checkbox-enabling JS
-

docs/explanation/index.md

@@ -19,3 +19,11 @@ Slices are defined via slice definition files and follow naming conventions.
 
 slices
 ```
+
+Slices can be defined following two different approaches.
+
+```{toctree}
+:maxdepth: 1
+
+slice-design-approaches
+```

docs/explanation/slice-design-approaches.md

@@ -0,0 +1,47 @@
+(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.
+
+## 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).
+
+  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.
+
+## 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)).

docs/how-to/slice-a-package.md

@@ -259,43 +259,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 schools of thought** when designing slices:
-
-```{list-table}
-:header-rows: 1
-:widths: 1 1
-
-* - Group by type
-  - Group by function
-* - 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).
-    ```{tip}
-    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,
-    - and others 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.
-    ```
-  - 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`.
-    ```{tip}
-    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,
-    - and 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)).
-    ```
-```
+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 <slice_design_approaches>`. This guide groups slices **by type of content**.
 
 - [ ] 2.1 **Choose the design approach that aligns best with your package**
 

docs/index.md

@@ -21,7 +21,7 @@ selecting and installing only the necessary slices from the full Ubuntu package
 * **Slices**: [Learn more about slices](explanation/slices) • 
 [Chisel releases](reference/chisel-releases/index) • 
 [chisel.yaml](reference/chisel-releases/chisel.yaml) •
-[Slice definitions](reference/chisel-releases/slice-definitions) • 
+[Slice definitions](reference/chisel-releases/slice-definitions) • [Slice design approaches](explanation/slice-design-approaches.md) • 
 [Install Ubuntu Pro package slices](how-to/install-pro-package-slices)
 
 ---------