Merge ~rkratky/ubuntu-governance-docs:docs-checks-update into ubuntu-governance-docs:main

[Robert Krátký]

Update Sphinx config & fix content to pass docs checks

Update Sphinx config

* Update syntax to pass linter
* Add matrix.to to linkcheck ignore list
* Fix Launchpad URLs

Fix content to pass docs checks

* Switch spellcheck to US English
* Fix spelling mistakes
* Add exceptions to ignore list
* Fix/update links to pass linkcheck
* Fix headings to sentence case

[Robert Krátký (rkratky)]

Forgot to mention that this MP follows up on https://code.launchpad.net/~rkratky/ubuntu-governance-docs/+git/ubuntu-governance-docs/+merge/482863 and should only be merged after it.

[Robie Basak (racb)]

Merged. Thanks!

review: Approve

diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
index e69de29..e23a5aa 100644
--- a/docs/.custom_wordlist.txt
+++ b/docs/.custom_wordlist.txt
@@ -0,0 +1,50 @@
+# Leave a blank line at the end of this file to support concatenation
+ACL
+Bacher
+Basak
+Fi
+FlatHub
+Flatpak
+GPG
+LibreOffice
+NVIDIA
+PPAs
+Robie
+SRU
+Samuele
+TBC
+TOC
+Vugt
+WCAG
+WSL
+Wi
+amd
+arm
+armhf
+auditability
+cjk
+cryptographically
+devel
+dfsg
+discoverable
+dvipng
+fonts
+freefont
+github
+gyre
+https
+kustom
+lang
+latexmk
+otf
+plantuml
+repos
+supportability
+tex
+texlive
+txt
+ubuntu
+utils
+wordlist
+xetex
+xindy
diff --git a/docs/.gitignore b/docs/.gitignore
index da6f688..bf16e0d 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,14 +1,25 @@
-/*env*/
+# Environment
+*env*/
 .sphinx/venv/
+
+# Sphinx
 .sphinx/warnings.txt
 .sphinx/.wordlist.dic
 .sphinx/.doctrees/
 .sphinx/node_modules/
-package*.json
+
+# Vale
+.sphinx/styles/*
+.sphinx/vale.ini
+
+# Build outputs
 _build
+
+# Node.js
+package*.json
+
+# Unrelated cache and config files
 .DS_Store
 __pycache__
 .idea/
 .vscode/
-.sphinx/styles/*
-.sphinx/vale.ini
\ No newline at end of file
diff --git a/docs/.sphinx/.markdownlint.json b/docs/.sphinx/.markdownlint.json
new file mode 100644
index 0000000..f42753f
--- /dev/null
+++ b/docs/.sphinx/.markdownlint.json
@@ -0,0 +1,27 @@
+{
+    "default": false,
+    "MD003": {
+        "style": "atx"
+    },
+    "MD013": {
+        "code_blocks": false,
+        "tables": false,
+        "stern": true,
+        "line_length": 150
+    },
+    "MD014": true,
+    "MD018": true,
+    "MD022": true,
+    "MD023": true,
+    "MD026": {
+        "punctuation": ".,;。，；"
+    },
+    "MD031": {
+        "list_items": false
+    },
+    "MD032": true,
+    "MD035": true,
+    "MD042": true,
+    "MD045": true,
+    "MD052": true
+}
\ No newline at end of file
diff --git a/docs/.sphinx/.pre-commit-config.yaml b/docs/.sphinx/.pre-commit-config.yaml
new file mode 100644
index 0000000..07e0b48
--- /dev/null
+++ b/docs/.sphinx/.pre-commit-config.yaml
@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: make-spelling
+        name: Run make spelling
+        entry: make -C docs spelling
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-linkcheck
+        name: Run make linkcheck
+        entry: make -C docs linkcheck
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-woke
+        name: Run make woke
+        entry: make -C docs woke
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt
index fb4137d..be5021a 100644
--- a/docs/.sphinx/.wordlist.txt
+++ b/docs/.sphinx/.wordlist.txt
@@ -1,13 +1,15 @@
-# This wordlist is from the Sphinx starter pack and should not be
-# modified. Add any custom terms to .custom_wordlist.txt instead.
-
+ACME
+ACME's
 addons
+AGPLv
 API
 APIs
 balancer
 Charmhub
 CLI
+DCO
 Diátaxis
+Dqlite
 dropdown
 EBS
 EKS
@@ -53,6 +55,7 @@ RTD
 subdirectories
 subfolders
 subtree
+TODO
 Ubuntu
 UI
 UUID
diff --git a/docs/.sphinx/_static/favicon.png b/docs/.sphinx/_static/favicon.png
deleted file mode 100644
index 7f175e4..0000000
Binary files a/docs/.sphinx/_static/favicon.png and /dev/null differ
diff --git a/docs/.sphinx/_static/project_specific.css b/docs/.sphinx/_static/project_specific.css
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/.sphinx/_static/project_specific.css
diff --git a/docs/.sphinx/_static/tag.png b/docs/.sphinx/_static/tag.png
deleted file mode 100644
index f6f6e5a..0000000
Binary files a/docs/.sphinx/_static/tag.png and /dev/null differ
diff --git a/docs/.sphinx/_templates/footer.html b/docs/.sphinx/_templates/footer.html
new file mode 100644
index 0000000..2d118a8
--- /dev/null
+++ b/docs/.sphinx/_templates/footer.html
@@ -0,0 +1,111 @@
+{# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #}
+
+<div class="related-pages">
+  {# mod: Per-page navigation #}
+  {% if meta %}
+    {% if 'sequential_nav' in meta %}
+      {% set sequential_nav = meta.sequential_nav %}
+    {% endif %}  
+  {% endif %}
+  {# mod: Conditional wrappers to control page navigation buttons #}
+  {% if sequential_nav != "none" -%}
+    {% if next and (sequential_nav == "next" or sequential_nav == "both") -%}
+      <a class="next-page" href="{{ next.link }}">
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Next") }}</span>
+          </div>
+          <div class="title">{{ next.title }}</div>
+        </div>
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+      </a>
+    {%- endif %}
+    {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%}
+      <a class="prev-page" href="{{ prev.link }}">
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Previous") }}</span>
+          </div>
+          {% if prev.link == pathto(root_doc) %}
+            <div class="title">{{ _("Home") }}</div>
+          {% else %}
+            <div class="title">{{ prev.title }}</div>
+          {% endif %}
+        </div>
+      </a>
+    {%- endif %}
+  {%- endif %}
+</div>
+<div class="bottom-of-page">
+  <div class="left-details">
+    {%- if show_copyright %}
+    <div class="copyright">
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e -%}
+          <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
+        {%- endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e -%}
+          Copyright &#169; {{ copyright }}
+        {%- endtrans %}
+      {%- endif %}
+    </div>
+    {%- endif %}
+
+    {# mod: removed "Made with" #}
+
+    {%- if last_updated -%}
+    <div class="last-updated">
+      {% trans last_updated=last_updated|e -%}
+        Last updated on {{ last_updated }}
+      {%- endtrans -%}
+    </div>
+    {%- endif %}
+
+    {%- if show_source and has_source and sourcename %}
+    <div class="show-source">
+      <a class="muted-link" href="{{ pathto('_sources/' + sourcename, true)|e }}"
+         rel="nofollow">Show source</a>
+    </div>
+    {%- endif %}
+  </div>
+  <div class="right-details">
+
+    {# mod: replaced RTD icons with our links #}
+
+    {% if discourse %}
+    <div class="ask-discourse">
+      <a class="muted-link" href="{{ discourse }}">Ask a question on Discourse</a>
+    </div>
+    {% endif %}
+
+    {% if irc %}
+    <div class="ask-mattermost">
+      <a class="muted-link" href="{{ irc }}">Ask a question on IRC</a>
+    </div>
+    {% endif %}
+
+    {% if matrix %}
+    <div class="ask-matrix">
+      <a class="muted-link" href="{{ matrix }}">Ask a question on Matrix</a>
+    </div>
+    {% endif %}
+
+    {% if launchpad_url and launchpad_version and launchpad_folder %}
+
+    {% if launchpad_issues %}
+    <div class="issue-github">
+      <a class="muted-link" href="{{ launchpad_issues }}">Open a Launchpad issue for this documentation</a>
+    </div>
+    {% endif %}
+
+    <div class="edit-github">
+      <a class="muted-link" href="{{ launchpad_url }}/tree{{ launchpad_folder }}{{ pagename }}{{ page_source_suffix }}">View this page on Launchpad</a>
+    </div>
+    {% endif %}
+
+
+    </div>
+  </div>
+</div>
diff --git a/docs/.sphinx/_templates/header.html b/docs/.sphinx/_templates/header.html
index 30c52c5..d0ac8e5 100644
--- a/docs/.sphinx/_templates/header.html
+++ b/docs/.sphinx/_templates/header.html
@@ -26,9 +26,9 @@
           </li>
           {% endif %}
 
-          {% if mattermost %}
+          {% if irc %}
           <li>
-            <a href="{{ mattermost }}" class="p-navigation__sub-link p-dropdown__link">Mattermost</a>
+            <a href="{{ irc }}" class="p-navigation__sub-link p-dropdown__link">IRC</a>
           </li>
           {% endif %}
 
@@ -38,9 +38,9 @@
           </li>
           {% endif %}
 
-          {% if github_url %}
+          {% if launchpad_url %}
           <li>
-            <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+            <a href="{{ launchpad_url }}" class="p-navigation__sub-link p-dropdown__link">Launchpad</a>
           </li>
           {% endif %}
 
diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py
index 23d8901..cb73a64 100644
--- a/docs/.sphinx/get_vale_conf.py
+++ b/docs/.sphinx/get_vale_conf.py
@@ -3,16 +3,18 @@
 import requests
 import os
 
-DIR=os.getcwd()
+DIR = os.getcwd()
 
 def main():
-
     if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"):
         print("Vale directory exists")
     else:
         os.makedirs(f"{DIR}/.sphinx/styles/Canonical")
 
-    url = "https://api.github.com/repos/canonical/praecepta/contents/styles/Canonical"
+    url = (
+        "https://api.github.com/repos/canonical/praecepta/"
+        + "contents/styles/Canonical"
+    )
     r = requests.get(url)
     for item in r.json():
         download = requests.get(item["download_url"])
@@ -20,22 +22,47 @@ def main():
         file.write(download.text)
         file.close()
 
+    # Update dictionary
+    if os.path.exists(f"{DIR}/.sphinx/styles/config/dictionaries"):
+        print("Dictionary directory exists")
+    else:
+        os.makedirs(f"{DIR}/.sphinx/styles/config/dictionaries")
+    url = (
+        "https://api.github.com/repos/canonical/praecepta/"
+        + "contents/styles/config/dictionaries"
+    )
+    r = requests.get(url)
+    for item in r.json():
+        download = requests.get(item["download_url"])
+        file = open(".sphinx/styles/config/dictionaries/" + item["name"], "w")
+        file.write(download.text)
+        file.close()
+
     if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"):
         print("Vocab directory exists")
     else:
         os.makedirs(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical")
-    
-    url = "https://api.github.com/repos/canonical/praecepta/contents/styles/config/vocabularies/Canonical"
+
+    url = (
+        "https://api.github.com/repos/canonical/praecepta/"
+        + "contents/styles/config/vocabularies/Canonical"
+    )
     r = requests.get(url)
     for item in r.json():
         download = requests.get(item["download_url"])
-        file = open(".sphinx/styles/config/vocabularies/Canonical/" + item["name"], "w")
+        file = open(
+            ".sphinx/styles/config/vocabularies/Canonical/" + item["name"],
+            "w"
+        )
         file.write(download.text)
         file.close()
-    config = requests.get("https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini")
+    config = requests.get(
+        "https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini"
+    )
     file = open(".sphinx/vale.ini", "w")
     file.write(config.text)
     file.close()
 
+
 if __name__ == "__main__":
     main()
diff --git a/docs/.sphinx/metrics/build_metrics.sh b/docs/.sphinx/metrics/build_metrics.sh
new file mode 100755
index 0000000..bd1ff1c
--- /dev/null
+++ b/docs/.sphinx/metrics/build_metrics.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# shellcheck disable=all
+
+links=0
+images=0
+
+# count number of links
+links=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o "<a " | wc -l)
+# count number of images
+images=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o "<img " | wc -l)
+
+# summarise latest metrics
+echo "Summarising metrics for build files (.html)..."
+echo -e "\tlinks: $links"
+echo -e "\timages: $images"
diff --git a/docs/.sphinx/metrics/source_metrics.sh b/docs/.sphinx/metrics/source_metrics.sh
new file mode 100755
index 0000000..07147d6
--- /dev/null
+++ b/docs/.sphinx/metrics/source_metrics.sh
@@ -0,0 +1,66 @@
+#!/bin/bash
+# shellcheck disable=all
+
+VENV=".sphinx/venv/bin/activate"
+
+files=0
+words=0
+readabilityWords=0
+readabilitySentences=0
+readabilitySyllables=0
+readabilityAverage=0
+readable=true
+
+# measure number of files (.rst and .md), excluding those in .sphinx dir
+files=$(find . -type d -path './.sphinx' -prune -o -type f \( -name '*.md' -o -name '*.rst' \) -print | wc -l)
+
+# calculate metrics only if source files are present
+if [ "$files" -eq 0 ]; then
+    echo "There are no source files to calculate metrics"
+else
+    # measure raw total number of words, excluding those in .sphinx dir
+    words=$(find . -type d -path './.sphinx' -prune -o \( -name '*.md' -o -name '*.rst' \) -exec cat {} + | wc -w)
+
+    # calculate readability for markdown source files
+    echo "Activating virtual environment to run vale..."
+    source "${VENV}"
+
+    for file in *.md *.rst; do
+        if [ -f "$file" ]; then
+            readabilityWords=$(vale ls-metrics "$file" | grep '"words"' | sed 's/[^0-9]*//g')
+            readabilitySentences=$(vale ls-metrics "$file" | grep '"sentences"' | sed 's/[^0-9]*//g')
+            readabilitySyllables=$(vale ls-metrics "$file" | grep '"syllables"' | sed 's/[^0-9]*//g')
+        fi
+    done
+
+    echo "Deactivating virtual environment..."
+    deactivate
+
+    # calculate mean number of words
+    if [ "$files" -ge 1 ]; then
+        meanval=$((readabilityWords / files))
+    else
+        meanval=$readabilityWords
+    fi
+
+    readabilityAverage=$(echo "scale=2; 0.39 * ($readabilityWords / $readabilitySentences) + (11.8 * ($readabilitySyllables / $readabilityWords)) - 15.59" | bc)
+
+    # cast average to int for comparison
+    readabilityAverageInt=$(echo "$readabilityAverage / 1" | bc)
+
+    # value below 8 is considered readable
+    if [ "$readabilityAverageInt" -lt 8 ]; then
+        readable=true
+    else
+        readable=false
+    fi
+
+    # summarise latest metrics
+    echo "Summarising metrics for source files (.md, .rst)..."
+    echo -e "\ttotal files: $files"
+    echo -e "\ttotal words (raw): $words"
+    echo -e "\ttotal words (prose): $readabilityWords"
+    echo -e "\taverage word count: $meanval"
+    echo -e "\treadability: $readabilityAverage"
+    echo -e "\treadable: $readable"
+fi
diff --git a/docs/.sphinx/pa11y.json b/docs/.sphinx/pa11y.json
index 8df0cb9..04dc1e1 100644
--- a/docs/.sphinx/pa11y.json
+++ b/docs/.sphinx/pa11y.json
@@ -6,4 +6,4 @@
   },
   "reporter": "cli",
   "standard": "WCAG2AA"
-}
\ No newline at end of file
+}
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
index c019f17..9ff666c 100644
--- a/docs/.sphinx/requirements.txt
+++ b/docs/.sphinx/requirements.txt
@@ -1,2 +1,4 @@
-git+https://github.com/canonical/canonical-sphinx@main#egg=canonical-sphinx
+canonical-sphinx[full]
 sphinx-autobuild
+sphinxcontrib-svg2pdfconverter[CairoSVG]
+sphinx-last-updated-by-git
diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml
index 5f3dbad..417a541 100644
--- a/docs/.sphinx/spellingcheck.yaml
+++ b/docs/.sphinx/spellingcheck.yaml
@@ -1,30 +1,30 @@
 matrix:
-- name: rST files
-  aspell:
-    lang: en
-    d: en_GB
-  dictionary:
-    wordlists:
-    - .sphinx/.wordlist.txt
-    - .custom_wordlist.txt
-    output: .sphinx/.wordlist.dic
-  sources:
-  - _build/**/*.html
-  pipeline:
-  - pyspelling.filters.html:
-      comments: false
-      attributes:
-      - title
-      - alt
-      ignores:
-      - code
-      - pre
-      - spellexception
-      - link
-      - title
-      - div.relatedlinks
-      - strong.command
-      - div.visually-hidden
-      - img
-      - a.p-navigation__link
-      - a.contributor
+  - name: rST files
+    aspell:
+      lang: en
+      d: en_US
+    dictionary:
+      wordlists:
+        - .sphinx/.wordlist.txt
+        - .custom_wordlist.txt
+      output: .sphinx/.wordlist.dic
+    sources:
+      - _build/**/*.html
+    pipeline:
+      - pyspelling.filters.html:
+          comments: false
+          attributes:
+            - title
+            - alt
+          ignores:
+            - code
+            - pre
+            - spellexception
+            - link
+            - title
+            - div.relatedlinks
+            - strong.command
+            - div.visually-hidden
+            - img
+            - a.p-navigation__link
+            - a.contributor
diff --git a/docs/Makefile b/docs/Makefile
index a861ba8..b9bdea0 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,11 +1,23 @@
-# This Makefile stub allows you to customize starter pack (SP) targets.
-# Consider this file as a bridge between your project
-# and the starter pack's predefined targets that reside in Makefile.sp.
+# Minimal makefile for Sphinx documentation
 #
-# You can add your own, non-SP targets here or override SP targets
-# to fit your project's needs. For example, you can define and use targets
-# named "install" or "run", but continue to use SP targets like "sp-install"
-# or "sp-run" when working on the documentation.
+# Add your customisation to `Makefile` instead.
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXDIR       = .sphinx
+SPHINXOPTS      ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
+SPHINXBUILD     ?= $(VENVDIR)/bin/sphinx-build
+SOURCEDIR       = .
+BUILDDIR        = _build
+VENVDIR         = $(SPHINXDIR)/venv
+PA11Y           = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
+VENV         	   = $(VENVDIR)/bin/activate
+TARGET          = *
+ALLFILES        =  *.rst **/*.rst
+METRICSDIR      = $(SOURCEDIR)/.sphinx/metrics
+REQPDFPACKS     = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng
+CONFIRM_SUDO    ?= N
+VALE_CONFIG     = $(SPHINXDIR)/vale.ini
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -23,8 +35,153 @@ help:
         "* check accessibility:                       make pa11y \n" \
         "* check style guide compliance:              make vale \n" \
         "* check style guide compliance on target:    make vale TARGET=* \n" \
+        "* check metrics for documentation:           make allmetrics \n" \
         "* other possible targets:                    make <TAB twice> \n" \
         "------------------------------------------------------------- \n"
 
+.PHONY: full-help woke-install spellcheck-install pa11y-install install run html \
+        epub serve clean clean-doc spelling spellcheck linkcheck woke \
+        allmetrics pa11y pdf-prep-force pdf-prep pdf vale-install vale
+
+full-help: $(VENVDIR)
+	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
+	@echo "Run 'make help' to see supported targets."
+
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(VENVDIR):
+	python3 -c "import venv" || \
+        (echo "You must install python3-venv before you can build the documentation."; exit 1)
+	@echo "... setting up virtualenv"
+	python3 -m venv $(VENVDIR)
+	. $(VENV); pip install $(PIPOPTS) --require-virtualenv \
+	    --upgrade -r $(SPHINXDIR)/requirements.txt \
+            --log $(VENVDIR)/pip_install.log
+	@test ! -f $(VENVDIR)/pip_list.txt || \
+            mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
+	@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
+	@touch $(VENVDIR)
+
+spellcheck-install:
+	@type aspell >/dev/null 2>&1 || \
+	{ \
+		echo "Installing system-wide \"aspell\" packages..."; \
+		confirm_sudo=$(CONFIRM_SUDO); \
+		if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \
+			read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \
+		fi; \
+		if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \
+			sudo apt-get install aspell aspell-en; \
+		else \
+			echo "Installation cancelled."; \
+		fi \
+	}
+
+pa11y-install:
+	@type $(PA11Y) >/dev/null 2>&1 || { \
+			echo "Installing \"pa11y\" from npm... \n"; \
+			mkdir -p $(SPHINXDIR)/node_modules/ ; \
+			npm install --prefix $(SPHINXDIR) pa11y; \
+		}
+
+install: $(VENVDIR)
+
+run: install
+	. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
+html: install
+	. $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+epub: install
+	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+serve: html
+	cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
+
+clean: clean-doc
+	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
+	rm -rf $(VENVDIR)
+	rm -rf $(SPHINXDIR)/node_modules/
+	rm -rf $(SPHINXDIR)/styles
+	rm -rf $(VALE_CONFIG)
+
+clean-doc:
+	git clean -fx "$(BUILDDIR)"
+	rm -rf $(SPHINXDIR)/.doctrees
+
+spellcheck: spellcheck-install
+	. $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
+
+spelling: html spellcheck
+
+linkcheck: install
+	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
+	exit 0
+
+pa11y: pa11y-install html
+	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
+
+vale-install: install
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale
+	@. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
+	@printf '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter
+	@printf '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/error.filter
+	@printf '.Name=="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/spelling.filter
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
+
+woke: vale-install
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+	@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@printf "Running Vale acceptable term check against $(TARGET). To change target set TARGET= with make command\n"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+vale: vale-install
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+	@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+vale-spelling: vale-install
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+	@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+pdf-prep: install
+	@for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \
+        grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \
+        (echo "\nPDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \
+        echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \
+        "Please be aware these packages will be installed to your system") && exit 1 ; done
+
+pdf-prep-force:
+	apt-get update
+	apt-get upgrade -y
+	apt-get install --no-install-recommends -y $(REQPDFPACKS) \
+
+pdf: pdf-prep
+	@. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	@rm ./$(BUILDDIR)/latex/front-page-light.pdf || true
+	@rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true
+	@find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} +
+	@rm -r $(BUILDDIR)/latex
+	@echo "\nOutput can be found in ./$(BUILDDIR)\n"
+
+allmetrics: html
+	@echo "Recording documentation metrics..."
+	@echo "Checking for existence of vale..."
+	. $(VENV)
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
+	@. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
+	@eval '$(METRICSDIR)/source_metrics.sh $(PWD)'
+	@eval '$(METRICSDIR)/build_metrics.sh $(PWD) $(METRICSDIR)'
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %:
-	$(MAKE) -f Makefile.sp sp-$@
+	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/Makefile.sp b/docs/Makefile.sp
deleted file mode 100644
index 80b5141..0000000
--- a/docs/Makefile.sp
+++ /dev/null
@@ -1,114 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-# `Makefile.sp` is from the Sphinx starter pack and should not be
-# modified.
-# Add your customisation to `Makefile` instead.
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXDIR     = .sphinx
-SPHINXOPTS    ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
-SPHINXBUILD   ?= $(VENVDIR)/bin/sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
-VENVDIR       = $(SPHINXDIR)/venv
-PA11Y         = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
-VENV          = $(VENVDIR)/bin/activate
-TARGET        = *
-ALLFILES      =  *.rst **/*.rst
-
-.PHONY: sp-full-help sp-woke-install sp-spellcheck-install sp-pa11y-install sp-install sp-run sp-html \
-        sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \
-        sp-pa11y Makefile.sp sp-vale
-
-sp-full-help: $(VENVDIR)
-	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	@echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
-	@echo "Run 'make help' to see supported targets."
-
-# If requirements are updated, venv should be rebuilt and timestamped.
-$(VENVDIR):
-	python3 -c "import venv" || \
-        (echo "You must install python3-venv before you can build the documentation."; exit 1)
-	@echo "... setting up virtualenv"
-	python3 -m venv $(VENVDIR)
-	. $(VENV); pip install --require-virtualenv \
-	    --upgrade -r $(SPHINXDIR)/requirements.txt \
-            --log $(VENVDIR)/pip_install.log
-	@test ! -f $(VENVDIR)/pip_list.txt || \
-            mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
-	@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
-	@touch $(VENVDIR)
-
-sp-woke-install:
-	@type woke >/dev/null 2>&1 || \
-            { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
-
-sp-spellcheck-install:
-	@type aspell >/dev/null 2>&1 || \
-            { echo "Installing aspell... \n"; sudo apt-get install aspell aspell-en; }
-
-sp-pa11y-install:
-	@type $(PA11Y) >/dev/null 2>&1 || { \
-			echo "Installing \"pa11y\" from npm... \n"; \
-			mkdir -p $(SPHINXDIR)/node_modules/ ; \
-			npm install --prefix $(SPHINXDIR) pa11y; \
-		}
-
-sp-install: $(VENVDIR)
-
-sp-run: sp-install
-	. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
-
-# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
-sp-html: sp-install
-	. $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
-
-sp-epub: sp-install
-	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
-
-sp-serve: sp-html
-	cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
-
-sp-clean: sp-clean-doc
-	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
-	rm -rf $(VENVDIR)
-	rm -rf $(SPHINXDIR)/node_modules/
-	rm -rf $(SPHINXDIR)/styles
-	rm -rf $(SPHINXDIR)/vale.ini
-
-sp-clean-doc:
-	git clean -fx "$(BUILDDIR)"
-	rm -rf $(SPHINXDIR)/.doctrees
-
-sp-spellcheck: sp-spellcheck-install
-	. $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
-
-sp-spelling: sp-html sp-spellcheck
-
-sp-linkcheck: sp-install
-	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
-	exit 0
-
-sp-woke: sp-woke-install
-	woke $(ALLFILES) --exit-1-on-failure \
-	    -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
-
-sp-pa11y: sp-pa11y-install sp-html
-	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
-
-sp-vale: sp-install
-	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
-	@. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
-	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
-	@echo ""
-	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
-	@echo ""
-	@. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET)
-
-
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile.sp
-	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
index a8b1cd9..7efa397 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,13 +17,13 @@ import datetime
 ############################################################
 
 # Product name
-project = 'Ubuntu Governance'
-author = 'Ubuntu Technical Board'
+project = "Ubuntu Governance"
+author = "Ubuntu Technical Board"
 
 # The title you want to display for the documentation in the sidebar.
 # You might want to include a version number here.
 # To not display any title, set this option to an empty string.
-html_title = project + ' Documentation'
+html_title = project + " Documentation"
 
 # The default value uses CC-BY-SA as the license and the current year
 # as the copyright year.
@@ -46,17 +46,17 @@ html_title = project + ' Documentation'
 #   -H 'Accept: application/vnd.github.v3.raw' \
 #   https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
 
-copyright = '%s CC-BY-SA, %s' % (datetime.date.today().year, author)
+copyright = "%s CC-BY-SA, %s" % (datetime.date.today().year, author)
 
 ## Open Graph configuration - defines what is displayed as a link preview
 ## when linking to the documentation from another website (see https://ogp.me/)
 # The URL where the documentation will be hosted (leave empty if you
 # don't know yet)
-ogp_site_url = 'https://canonical-ubuntu-governance-docs.readthedocs-hosted.com/'
+ogp_site_url = "https://canonical-ubuntu-governance-docs.readthedocs-hosted.com/"
 # The documentation website name (usually the same as the product name)
 ogp_site_name = project
 # The URL of an image or logo that is used in the preview
-ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
+ogp_image = "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg"
 
 # Update with the local path to the favicon for your product
 # (default is the circle of friends)
@@ -65,55 +65,37 @@ ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg
 # (Some settings must be part of the html_context dictionary, while others
 #  are on root level. Don't move the settings.)
 html_context = {
-
     # Change to the link to the website of your product (without "https://")
     # For example: "ubuntu.com/lxd" or "microcloud.is"
     # If there is no product website, edit the header template to remove the
     # link (see the readme for instructions).
-    'product_page': 'wiki.ubuntu.com/TechnicalBoard',
-
+    "product_page": "wiki.ubuntu.com/TechnicalBoard",
     # Add your product tag (the orange part of your logo, will be used in the
     # header) to ".sphinx/_static" and change the path here (start with "_static")
     # (default is the circle of friends)
     # 'product_tag': '_static/tag.png',
-
     # Change to the discourse instance you want to be able to link to
     # using the :discourse: metadata at the top of a file
     # (use an empty value if you don't want to link)
-    'discourse': 'https://discourse.ubuntu.com',
-
-    # Change to the Mattermost channel you want to link to
-    # (use an empty value if you don't want to link)
-    'mattermost': '',
-
-    # Change to the Matrix channel you want to link to
-    # (use an empty value if you don't want to link)
-    'matrix': '',
-
-    # Change to the GitHub URL for your project
-    # This is used, for example, to link to the source files and allow creating GitHub issues directly from the documentation.
-    'github_url': 'https://launchpad.net/~techboard/ubuntu-governance-docs',
-
+    "discourse": "https://discourse.ubuntu.com",
+    # Your IRC channel
+    # "irc": "https://web.libera.chat/gamja/?channels=%23ubuntu-devel",
+    # Your Matrix channel URL
+    "matrix": "https://matrix.to/#/#devel:ubuntu.com",
+    # Your Launchpad URL
+    "launchpad_url": "https://git.launchpad.net/ubuntu-governance-docs",
     # Change to the branch for this version of the documentation
-    'github_version': 'main',
-
+    "launchpad_version": "main",
     # Change to the folder that contains the documentation
     # (usually "/" or "/docs/")
-    'github_folder': '/docs/',
-
-    # Change to an empty value if your GitHub repo doesn't have issues enabled.
-    # This will disable the feedback button and the issue link in the footer.
-    'github_issues': '',
-
+    "launchpad_folder": "/docs/",
+    # Change to an empty value to disable the issue link in the footer.
+    "launchpad_issues": "https://bugs.launchpad.net/techboard/+filebug",
     # Controls the existence of Previous / Next buttons at the bottom of pages
     # Valid options: none, prev, next, both
-    # 'sequential_nav': "none",
-
-    # Uncomment to disable displaying the contributors for each file.
-    # (You can also limit the time frame for displaying contributors
-    # by setting a "display_contributors_since" variable.)
-    # "display_contributors": False,
-
+    "sequential_nav": "both",
+    # Controls whether to display the contributors for each file
+    "display_contributors": False,
 }
 
 # If your project is on documentation.ubuntu.com, specify the project
@@ -124,8 +106,8 @@ html_context = {
 # You can comment them out if you don't need this (but you can also just
 # leave them).
 
-html_static_path = ['.sphinx/_static']
-templates_path = ['.sphinx/_templates']
+html_static_path = [".sphinx/_static"]
+templates_path = [".sphinx/_templates"]
 
 ############################################################
 ### Redirects
@@ -144,15 +126,11 @@ redirects = {}
 ############################################################
 
 # Links to ignore when checking links
-linkcheck_ignore = [
-    'http://127.0.0.1:8000'
-    ]
+linkcheck_ignore = ["http://127.0.0.1:8000", "https://matrix.to"]
 
 # Pages on which to ignore anchors
 # (This list will be appended to linkcheck_anchors_ignore_for_url)
-linkcheck_anchors_ignore_for_url = [
-    r'https://github\.com/.*'
-]
+linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"]
 
 ############################################################
 ### Additions to default configuration
@@ -165,9 +143,9 @@ linkcheck_anchors_ignore_for_url = [
 # substitution, deflist, linkify
 # If you need more extensions, add them here.
 myst_enable_extensions = {
-    'colon_fence',
-    'substitution',
-    }
+    "colon_fence",
+    "substitution",
+}
 
 # You must include the canonical_sphinx extension here.
 # This extension automatically enables the following Sphinx extensions:
@@ -178,13 +156,13 @@ myst_enable_extensions = {
 # If you need more extensions, add them here (in addition to
 # canonical_sphinx).
 extensions = [
-    'canonical_sphinx'
-    ]
+    "canonical_sphinx",
+    "sphinxcontrib.cairosvgconverter",
+    "sphinx_last_updated_by_git",
+]
 
 # Add files or directories that should be excluded from processing.
-exclude_patterns = [
-    'doc-cheat-sheet*',
-    ]
+exclude_patterns = []
 
 # Add custom CSS files (located in .sphinx/_static/)
 # html_css_files = []
@@ -215,11 +193,11 @@ exclude_patterns = [
 ## Add any configuration that is not covered by the common conf.py file.
 
 # Define a :center: role that can be used to center the content of table cells.
-rst_prolog = '''
+rst_prolog = """
 .. role:: center
    :class: align-center
-'''
+"""
 
 # Workaround for https://github.com/canonical/canonical-sphinx/issues/34
-if not 'discourse_prefix' in html_context and 'discourse' in html_context:
-    html_context['discourse_prefix'] = html_context['discourse'] + '/t/'
+if not "discourse_prefix" in html_context and "discourse" in html_context:
+    html_context["discourse_prefix"] = html_context["discourse"] + "/t/"
diff --git a/docs/index.md b/docs/index.md
index f1df1f6..bba4f6e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,4 +1,4 @@
-# Ubuntu Governance Docs
+# Ubuntu governance docs
 
 ```{toctree}
 :maxdepth: 2
@@ -22,11 +22,11 @@ As a community we adhere to the Ubuntu code of conduct.
 * **[Get support](https://askubuntu.com/)**:
 Ask Ubuntu is a question and answer site for Ubuntu users and developers.
 
-* **[Join our online chat](https://web.libera.chat/gamja/?channels=%23channel)**:
-Meet us in `#channel` on IRC Libera.Chat.
+* **Join our online chat**:
+Meet us in the [Ubuntu Development](https://matrix.to/#/#devel:ubuntu.com) channel on Matrix.
 
-* **[Report bugs](https://launchpad.net/~techboard/ubuntu-governance-docs/+filebug)**:
-We want to know about the problems so we can fix them.
+* **[Report bugs](https://launchpad.net/techboard/+filebug)**:
+We want to know about the problems, so we can fix them.
 
-* **[Contribute docs](https://launchpad.net/~techboard/ubuntu-governance-docs)**:
-The documentation sources on GitHub.
+* **[Contribute docs](https://launchpad.net/ubuntu-governance-docs)**:
+The documentation sources on Launchpad.
diff --git a/docs/policy/3rd-party-software-sources.md b/docs/policy/3rd-party-software-sources.md
index 40675dd..4ff3a94 100644
--- a/docs/policy/3rd-party-software-sources.md
+++ b/docs/policy/3rd-party-software-sources.md
@@ -3,9 +3,9 @@
 
 ## Purpose
 
-Ubuntu maintains its own standards for certain aspects of quality and behaviour in relation to software that it ships, with the goal that users can expect and rely upon this. For example, the "Ubuntu LTS" label comes with an expectation that we do not generally disrupt users with free-for-all improvements during the lifetime of such an LTS release.
+Ubuntu maintains its own standards for certain aspects of quality and behavior in relation to software that it ships, with the goal that users can expect and rely upon this. For example, the "Ubuntu LTS" label comes with an expectation that we do not generally disrupt users with free-for-all improvements during the lifetime of such an LTS release.
 
-With an increasing reliance on snaps to ship to Ubuntu users by default, it's important to continue setting appropriate expectations for quality and behaviour outside the traditional "deb" archive and ensuring that they are met. For example, snaps are intended to delegate quality considerations and decisions to the snap publisher: anyone can publish snaps. But we want the snaps that Ubuntu ships by default, or otherwise makes available by default, to meet our own minimum quality standards.
+With an increasing reliance on snaps to ship to Ubuntu users by default, it's important to continue setting appropriate expectations for quality and behavior outside the traditional "deb" archive and ensuring that they are met. For example, snaps are intended to delegate quality considerations and decisions to the snap publisher: anyone can publish snaps. But we want the snaps that Ubuntu ships by default, or otherwise makes available by default, to meet our own minimum quality standards.
 
 This document is intended to set a baseline for these expectations in general—for debs, snaps and any other packaging system that might be used in the future.
 
@@ -19,17 +19,17 @@ This document specifies Ubuntu's baseline policy requirements on all software pr
 
 1. Someone may want the installation of a deb from the Ubuntu archive to automatically enable and pull in a Flatpak from FlatHub.
 
-1. The "Software Centre" of an Ubuntu flavour may choose to enable, by default, a third party package repository of some form.
+1. The "Software Center" of an Ubuntu flavor may choose to enable, by default, a third party package repository of some form.
 
-Any behaviour of this kind must comply with the requirements specified in this document.
+Any behavior of this kind must comply with the requirements specified in this document.
 
-The requirements documented here are intended to fulfil user expectations and similar issues that arise in relation to software origin. These are not the only set of requirements that exist. For example, Debian policy and the derived Ubuntu policy still apply for debs.
+The requirements documented here are intended to fulfill user expectations and similar issues that arise in relation to software origin. These are not the only set of requirements that exist. For example, Debian policy and the derived Ubuntu policy still apply for debs.
 
 ### Not in scope
 
 If all routes to install some other software involves users explicitly choosing to opt in to some other software source and such that they are reasonably informed or is otherwise reasonably expected to understand that this choice means that Ubuntu is not responsible for software installed from this source, then this policy does not apply.
 
-## General Requirements
+## General requirements
 
 ### Review and approvals
 
@@ -41,17 +41,17 @@ For example, the Technical Board expects to decline to approve PPAs as a mechani
 
 Various packages are exceptional for various reasons, and Ubuntu has a tradition of being pragmatic about this in order to deliver the best experience to our users. This document merely specifies the baseline. Exceptions will continue to be made on a case-by-case basis by the Technical Board or by any other teams as delegated by them. Exceptions granted by the Technical Board are documented in {ref}`appendix-a-general-exceptions`.
 
-## Specific Principles
+## Specific principles
 
-### Principle 1: behaviour will remain "stable" for the lifetime of an Ubuntu release.
+### Principle 1: behavior will remain "stable" for the lifetime of an Ubuntu release.
 
 The package publisher must agree that the package and any subsequent updates presented to Ubuntu users by default will remain stable for the lifetime of the Ubuntu release.
 
-"Stable" means that behaviour from users' perspectives will not change, except to fix bugs, unless the change already matches a category of standing exception generally granted for Ubuntu packages themselves, as defined at [https://wiki.ubuntu.com/StableReleaseUpdates\#When](https://wiki.ubuntu.com/StableReleaseUpdates\#When) under the "When" section.
+"Stable" means that behavior from users' perspectives will not change, except to fix bugs, unless the change already matches a category of standing exception generally granted for Ubuntu packages themselves, as defined at [Stable Release Updates](https://wiki.ubuntu.com/StableReleaseUpdates\#When) under the "When" section.
 
 Since updates may be made to the package without review by Ubuntu, this requirement is enforced by trust only. Ubuntu would appreciate consultation to discuss where we stand on individual issues that fall close to the line. Ultimately, if Ubuntu is unhappy about the way this requirement is being met, then the package, and other packages from the same maintenance teams, may be removed from publication by default in future Ubuntu releases to help meet the user expectation of stable release stability.
 
-Rationale: Ubuntu users expect, for most packages, that a stable Ubuntu release remains stable in the sense that functionality and behaviour does not change until they opt-in to upgrading to a subsequent release. There are a number of pragmatic exceptions to this rule; the list of these should continue to be managed under the governance of the Technical Board.
+Rationale: Ubuntu users expect, for most packages, that a stable Ubuntu release remains stable in the sense that functionality and behavior does not change until they opt-in to upgrading to a subsequent release. There are a number of pragmatic exceptions to this rule; the list of these should continue to be managed under the governance of the Technical Board.
 
 ### Principle 2: Ubuntu developers can override and patch packages
 
@@ -75,7 +75,7 @@ Since updates may be made to the package without review by Ubuntu, this requirem
 
 Rationale: this is an expectation that exists for the Ubuntu deb archive, and should continue to exist for anything Ubuntu ships by default.
 
-### Principle 4: licensing would be acceptable to Ubuntu ie. dfsg-free
+### Principle 4: licensing would be acceptable to Ubuntu i.e. dfsg-free
 
 The package must be licensed under terms acceptable under the [Debian Free Software Guidelines](https://www.debian.org/social\_contract\#guidelines).
 
@@ -83,9 +83,9 @@ Rationale: these are the same requirements Ubuntu has always applied to its main
 
 ### Principle 5: packages are built on a build farm that is trusted by the Ubuntu project
 
-Packages must be built by and published from Ubuntu’s own infrastructure (ie. Launchpad and the Snap Store).
+Packages must be built by and published from Ubuntu’s own infrastructure (i.e. Launchpad and the Snap Store).
 
-Rationale: user security depends on trustworthiness of the build and publication process and is best served by keeping the number of organisations that must be trusted to a minimum; namely, one.
+Rationale: user security depends on trustworthiness of the build and publication process and is best served by keeping the number of organizations that must be trusted to a minimum; namely, one.
 
 ### Principle 6: sources for published builds are retained and publicly available
 
@@ -106,7 +106,7 @@ It must be possible for a user to locate and post in a public bug tracker about 
 Rationale: an inability to do this harms the ability for users to develop and share modifications to packages. Such modifications are the essence of Free Software and the ability to communicate with other users in a bug database is a long-standing expectation of users of Ubuntu.
 
 (appendix-a-general-exceptions)=
-## Appendix A: General Exceptions
+## Appendix A: General exceptions
 
 ### Exception to Principle 7: available on all architectures supported by Ubuntu
 
@@ -116,7 +116,7 @@ If Launchpad does not allow the general public to build on a particular architec
 
 This section only applies to a package that, regardless of architecture support, could only practically be used exclusively by desktop users.
 
-If such a package is only used for the purposes of being made available in some flavours (by seeding or presenting it for user installation in a flavour-specific way), then only the architectures supported by those flavours need to be supported.
+If such a package is only used for the purposes of being made available in some flavors (by seeding or presenting it for user installation in a flavor-specific way), then only the architectures supported by those flavors need to be supported.
 
 This exception may exclude the opportunity for those architectures from doing “remote desktop hosting” because widespread support across packages for those architectures may be missing as a result. We think this is an acceptable trade-off between this possibility and the burden of maintaining such packages in those architectures.
 
@@ -124,48 +124,48 @@ This exception may exclude the opportunity for those architectures from doing 
 
 If it is not practical to maintain full architecture support for some specific package, and the more general exceptions above cannot be used, then the Technical Board may grant and document an exception here. The following packages currently have such exceptions:
 
-* Firefox. Must build on amd64, arm64 and armhf. Reason: unsupported upstream, too complex to fix at the distro level.
-* snap-store (ie. the new one currently on the preview channel).
-* Ubuntu desktop installer. Uses Flutter for which there isn’t a runtime on other arches.
+* Firefox. Must build on amd64, arm64 and armhf. Reason: unsupported upstream, too complex to fix at the distribution level.
+* snap-store (i.e. the new one currently on the preview channel).
+* Ubuntu desktop installer. Uses Flutter for which there isn’t a runtime on other architectures.
 
-## Appendix B: Snap Specifics
+## Appendix B: Snap specifics
 
-### How Snaps Implement the Principles
+### How snaps implement the principles
 
 #### Track mappings and ICE branches
 
 Principles 1 and 2 are implemented in snaps through the use of *track mappings* and *ICE branches* as defined here. Tracks and branches are aspects of [snap channels](https://snapcraft.io/docs/channels).
 
-* **Track mappings.** To maintain stable behaviour for the lifetime of a given Ubuntu release, that release is mapped to a snap track for each snap that is within scope. For example, we might declare that snap package “foo” shall, by default on a fresh installation of Ubuntu 24.04, be installed and mapped to track “15” of the “foo” snap package. This mapping would be expected to remain fixed for the lifetime of Ubuntu 24.04.
-* **ICE branches.** snapd may be configured to follow a given channel branch for a particular installed snap, and this shall be done for all snaps when their installation falls under the scope of this policy. The branch name shall be “ubuntu-XX.YY”, where XX.YY is the Ubuntu release version in question. For example, on Ubuntu 24.04, the firefox snap should track “latest/stable/ubuntu-24.04” by default. For the purposes of this policy, we’ll call this snap branch the in-case-of emergency branch (“ICE branch”). Since the Firefox snap holds an exception to principle 1, only principle 2 is implemented in this example.
+* **Track mappings.** To maintain stable behavior for the lifetime of a given Ubuntu release, that release is mapped to a snap track for each snap that is within scope. For example, we might declare that snap package “foo” shall, by default on a fresh installation of Ubuntu 24.04, be installed and mapped to track “15” of the “foo” snap package. This mapping would be expected to remain fixed for the lifetime of Ubuntu 24.04.
+* **ICE branches.** `snapd` may be configured to follow a given channel branch for a particular installed snap, and this shall be done for all snaps when their installation falls under the scope of this policy. The branch name shall be `ubuntu-XX.YY`, where `XX.YY` is the Ubuntu release version in question. For example, on Ubuntu 24.04, the Firefox snap should track `latest/stable/ubuntu-24.04` by default. For the purposes of this policy, we’ll call this snap branch the in-case-of emergency branch (“ICE branch”). Since the Firefox snap holds an exception to principle 1, only principle 2 is implemented in this example.
 
 When a user upgrades to a new Ubuntu distribution release, the track mapping is often expected to change. As an exception, the track mapping may also change during the lifetime of a stable release.
 
-##### Behaviour on release upgrades
+##### Behavior on release upgrades
 
-1. **Snaps installed by default.** If a snap was installed by default on an Ubuntu installation, it is preferable for users to automatically refresh to the new default snap channel automatically (including track, risk and branch) regardless of whether they have previously deviated from previous default ICE-enabled channel. This practice is consistent with other package types and PPAs where release upgrades aim to create a consistent ‘standard’ configuration. For example: on upgrade from 24.04 to 26.04, the Software Centre snap should be refreshed to the track mapping and stable risk channel for 26.04 regardless of whether the user had adjusted it before.
-1. **Snaps otherwise within scope.** If a snap was not installed by default, but instead installed by a different path that nevertheless falls within the scope of this document, then it should be refreshed to the new track mapping only if the user had not deviated from it tracking the ICE branch. For example, the lxd transitional deb on 24.10 might arrange for the snap to track 5.20/stable/ubuntu-24.10 based on its track mapping for 24.10. If on upgrade to 25.04 it is still tracking a branch that matches /^ubuntu-/ and the track mapping has changed to 5.21, then it would be migrated to track 5.21/stable/ubuntu-25.04 instead. However, had the user deviated away from tracking the ICE branch, that case would be indistinguishable from the following case “Snaps not in scope” and behaviour shall be as if the snap were no longer in scope. Therefore, users can opt a snap out of falling under this case by bringing them out of scope using `snap refresh` or `snap switch` to no longer track the ICE branch.
+1. **Snaps installed by default.** If a snap was installed by default on an Ubuntu installation, it is preferable for users to automatically refresh to the new default snap channel automatically (including track, risk and branch) regardless of whether they have previously deviated from previous default ICE-enabled channel. This practice is consistent with other package types and PPAs where release upgrades aim to create a consistent ‘standard’ configuration. For example: on upgrade from 24.04 to 26.04, the Software Center snap should be refreshed to the track mapping and stable risk channel for 26.04 regardless of whether the user had adjusted it before.
+1. **Snaps otherwise within scope.** If a snap was not installed by default, but instead installed by a different path that nevertheless falls within the scope of this document, then it should be refreshed to the new track mapping only if the user had not deviated from it tracking the ICE branch. For example, the `lxd` transitional deb on 24.10 might arrange for the snap to track `5.20/stable/ubuntu-24.10` based on its track mapping for 24.10. If on upgrade to 25.04 it is still tracking a branch that matches `/^ubuntu-/` and the track mapping has changed to 5.21, then it would be migrated to track `5.21/stable/ubuntu-25.04` instead. However, had the user deviated away from tracking the ICE branch, that case would be indistinguishable from the following case “Snaps not in scope” and behavior shall be as if the snap were no longer in scope. Therefore, users can opt a snap out of falling under this case by bringing them out of scope using `snap refresh` or `snap switch` to no longer track the ICE branch.
 1. **Snaps not in scope.** If the snap is not installed by default on an Ubuntu installation and was installed by the user manually, then the channel it tracks should not change. This case is detected by the previous channel being tracked not having an ICE branch included.
 
-Track mapping changes during release upgrades shall be handled between ubuntu-release-upgrader and transitional debs as required. If the snap being migrated was previously not tracking an ICE branch, the user should be notified so that they can manually return to the previous state if preferred.
+Track mapping changes during release upgrades shall be handled between `ubuntu-release-upgrader` and transitional debs as required. If the snap being migrated was previously not tracking an ICE branch, the user should be notified so that they can manually return to the previous state if preferred.
 
-Exceptional track mapping changes during the lifetime of an Ubuntu release may occur. These would require approval from the Technical Board on a case-by-case basis. They would be expected to be handled via the SRU of a suitable deb package which would then implement this logic in its postinst. We do not consider it necessary to implement this unless and until such an exception becomes necessary.
+Exceptional track mapping changes during the lifetime of an Ubuntu release may occur. These would require approval from the Technical Board on a case-by-case basis. They would be expected to be handled via the SRU of a suitable deb package which would then implement this logic in its `postinst` script. We do not consider it necessary to implement this unless and until such an exception becomes necessary.
 
 ##### ICE branch details
 
-Normally, ICE branches are tracked by the snapd client but nevertheless do not exist, and in this case snapd falls back to not using any branch. For example, while tracking “latest/stable/ubuntu-24.04” it would install and maintain Firefox from the “latest/stable” channel so long as “latest/stable/ubuntu-24.04” does not exist. However, it does still continue to track “latest/stable/ubuntu-24.04” even if it has applied this fallback mechanism, so future publication into the ICE branch would cause users to switch to this published build, enabling principle 2\.
+Normally, ICE branches are tracked by the `snapd` client but nevertheless do not exist, and in this case `snapd` falls back to not using any branch. For example, while tracking `latest/stable/ubuntu-24.04` it would install and maintain Firefox from the `latest/stable` channel so long as `latest/stable/ubuntu-24.04` does not exist. However, it does still continue to track `latest/stable/ubuntu-24.04` even if it has applied this fallback mechanism, so future publication into the ICE branch would cause users to switch to this published build, enabling principle 2.
 
-After a release upgrade, the name of an ICE branch changes. If “Behaviour on release upgrades” above requires the snap to be migrated, then the ICE branch name being tracked should also change as part of the upgrade.
+After a release upgrade, the name of an ICE branch changes. If “Behavior on release upgrades” above requires the snap to be migrated, then the ICE branch name being tracked should also change as part of the upgrade.
 
-To identify “Snaps otherwise within scope”, for robustness, we shall consider the tracking of any ICE branch name as a qualifier, not just the specific ICE branch matching the release from which we are upgrading. For example, if the system is tracking “latest/beta/ubuntu-18.04” at the time of upgrading from Ubuntu 22.04 to Ubuntu 24.04, the upgrade process would change the channel being tracked to “15/stable/ubuntu-24.04” if that’s what “Behaviour on release upgrades” says, even though the previous track didn’t match the previous mapping, and even though the previous ICE branch name didn’t match the release from which we were upgrading.
+To identify “Snaps otherwise within scope”, for robustness, we shall consider the tracking of any ICE branch name as a qualifier, not just the specific ICE branch matching the release from which we are upgrading. For example, if the system is tracking `latest/beta/ubuntu-18.04` at the time of upgrading from Ubuntu 22.04 to Ubuntu 24.04, the upgrade process would change the channel being tracked to `15/stable/ubuntu-24.04` if that’s what “Behavior on release upgrades” says, even though the previous track didn’t match the previous mapping, and even though the previous ICE branch name didn’t match the release from which we were upgrading.
 
 ##### Summary
 
-The specifics are documented above, but to avoid any doubt, the effect of the snap implementations of principles 1 and 2 are that snaps installed that are in scope shall usually combine to track a channel where the track is specified by the track mapping, the risk is `stable` and the branch is `ubuntu-XX.YY` where `XX.YY` is the Ubuntu release of the installed system. Exceptionally, if the Technical Board has granted an exception from principle 1 (eg. Firefox) then the track would be `latest` instead. For example, if Libreoffice were to ship as a snap and did not have an exception against principle 1 then a default 24.04 desktop system might track `24/stable/ubuntu-24.04`. It would be required that there is a `24` track in this example since use of a `latest` track would violate principle 1\. Firefox on the same system would be expected to track `latest/stable/ubuntu-24.04` since it does have an exception against principle 1\.
+The specifics are documented above, but to avoid any doubt, the effect of the snap implementations of principles 1 and 2 are that snaps installed that are in scope shall usually combine to track a channel where the track is specified by the track mapping, the risk is `stable` and the branch is `ubuntu-XX.YY` where `XX.YY` is the Ubuntu release of the installed system. Exceptionally, if the Technical Board has granted an exception from principle 1 (e.g. Firefox) then the track would be `latest` instead. For example, if LibreOffice were to ship as a snap and did not have an exception against principle 1 then a default 24.04 desktop system might track `24/stable/ubuntu-24.04`. It would be required that there is a `24` track in this example since use of a `latest` track would violate principle 1. Firefox on the same system would be expected to track `latest/stable/ubuntu-24.04` since it does have an exception against principle 1.
 
-#### Principle 1: behaviour will remain "stable" for the lifetime of an Ubuntu release
+#### Principle 1: behavior will remain "stable" for the lifetime of an Ubuntu release
 
-This is achieved by use of track mappings combined with established behaviour by the snapd client. The track mapping of a snap that is within scope must use a track for which upstream commits to maintain this principle. This means that `latest` is not a permitted track mapping unless an exception exists as below.
+This is achieved by use of track mappings combined with established behavior by the `snapd` client. The track mapping of a snap that is within scope must use a track for which upstream commits to maintain this principle. This means that `latest` is not a permitted track mapping unless an exception exists as below.
 
 We then rely on the snap maintainer to keep the track stable. This is the normal expectation anyway for snap tracks that aren’t `latest`; we shall rely on trust as is permitted by the requirement.
 
@@ -177,7 +177,7 @@ If the Technical Board were to grant an exception after release, then the mappin
 
 #### Principle 2: Ubuntu developers will be able to override and patch the package
 
-This is achieved by use of ICE branches combined with established behaviour by the snapd client.
+This is achieved by use of ICE branches combined with established behavior by the `snapd` client.
 
 This requires the Technical Board to have the ultimate authority to publish into such an ICE branch. It is a condition of the permission to include snaps into Ubuntu that the Snap Store admins defer to the Technical Board’s authority and permit such a publication should, in the sole opinion of the Technical Board, the need arises.
 
@@ -185,7 +185,7 @@ This requires the Technical Board to have the ultimate authority to publish into
 
 We will document explicit agreement from individual snap maintainers.
 
-#### Principle 4: licensing would be acceptable to Ubuntu ie. dfsg-free
+#### Principle 4: licensing would be acceptable to Ubuntu i.e. dfsg-free
 
 This will be managed to the same standard as Ubuntu’s deb archive. At a minimum, an initial check is required by a competent person before moving a snap within scope, and a process by which deviations can be reported and resolved.
 
@@ -207,7 +207,7 @@ Compliance will be checked for each in-scope snap once. A bug can be filed again
 
 #### Additional requirements
 
-The TB agreed in their meeting on 30 May 2023 that any new seeded snaps must be announced in advance to ubuntu-devel@, to help the TB monitor the quality of seeded snaps whose maintainers may not necessarily be Ubuntu developers.
+The TB agreed in their meeting on 30 May 2023 that any new seeded snaps must be announced in advance to the [ubuntu-devel@](https://lists.ubuntu.com/mailman/listinfo/ubuntu-devel) mailing list, to help the TB monitor the quality of seeded snaps whose maintainers may not necessarily be Ubuntu developers.
 
 ## Appendix C: Matters not yet addressed
 
@@ -227,67 +227,67 @@ The following snaps are identified to fall under the scope of these requirements
 
 Via Ubuntu-specific deb packages
 
-* chromium
+* `chromium`
 
-* firefox
+* `firefox`
 
-* lxd (also seeded)
+* `lxd` (also seeded)
 
-* snapcraft
+* `snapcraft`
 
 Via deb package as synced from Debian:
 
-* cyphesis-cpp
+* `cyphesis-cpp`
 
-* ember
+* `ember`
 
 Via [seeds](https://bazaar.launchpad.net/\~ubuntu-archive/ubuntu-archive-scripts/trunk/view/head:/update-seeds)
 
-* snapd itself (Samuele says: *snapd itself is also a snap that we ship in images, it uses latest/stable like firefox and the deb has a SRU-exception(?). The snapd deb also installs it if not already present when installing snaps*)
+* `snapd` itself (Samuele says: *`snapd` itself is also a snap that we ship in images, it uses latest/stable like `firefox` and the deb has a SRU-exception(?). The `snapd` deb also installs it if not already present when installing snaps*)
 
-* freeshow (Ubuntu Studio)
+* `freeshow` (Ubuntu Studio)
 
-* Some of gnome-3-{28,34,38}-{18,20}04
+* Some of `gnome-3-{28,34,38}-{18,20}04`
 
-* gtk-common-themes
+* `gtk-common-themes`
 
 * Only in Bionic:
 
-  * gnome-calculator
+  * `gnome-calculator`
 
-  * gnome-characters
+  * `gnome-characters`
 
-  * gnome-log
+  * `gnome-log`
 
-  * gnome-system-monitor
+  * `gnome-system-monitor`
 
-  * pulsemixer (MATE)
+  * `pulsemixer` (MATE)
 
-* snapd-desktop-integration
+* `snapd-desktop-integration`
 
-* software-boutique (MATE)
+* `software-boutique` (MATE)
 
-* ubuntu-budgie-welcome (Budgie)
+* `ubuntu-budgie-welcome` (Budgie)
 
-* ubuntu-mate-welcome (MATE)
+* `ubuntu-mate-welcome` (MATE)
 
-* lxd (also through transitional deb)
+* `lxd` (also through transitional deb)
 
-* snap-store
+* `snap-store`
 
-* ubuntu-desktop-installer/classic=latest/edge (from wsl)
+* `ubuntu-desktop-installer/classic=latest/edge` (from WSL)
 
 Via installer image generation:
 
-* subiquity
+* `subiquity`
 
 #### Principle 3: the package maintainer agrees to maintain the package for the lifetime of the Ubuntu release
 
 We will arrange a place where agreements made can be documented and complete that for each snap within scope.
 
-#### Principle 4: licensing would be acceptable to Ubuntu ie. dfsg-free
+#### Principle 4: licensing would be acceptable to Ubuntu i.e. dfsg-free
 
-* Individual analysis pending: chromium, cyphesis-cpp, ember, firefox, freeshow, gnome-3-38-2004, gtk-common-themes, lxd, snapcraft, snapd-desktop-integration, snap-store, ubuntu-desktop-installer, subiquity.
+* Individual analysis pending: `chromium`, `cyphesis-cpp`, `ember`, `firefox`, `freeshow`, `gnome-3-38-2004`, `gtk-common-themes`, `lxd`, `snapcraft`, `snapd-desktop-integration`, `snap-store`, `ubuntu-desktop-installer`, `subiquity`.
 
 * Snaps compliant: TBC
 
@@ -299,7 +299,7 @@ This is not currently the case, although the required metadata may be available 
 
 #### Principle 7: published on all architectures supported by Ubuntu
 
-* Individual analysis pending: chromium, cyphesis-cpp, ember, firefox, freeshow, gnome-3-38-2004, gtk-common-themes, lxd, snapcraft, snapd-desktop-integration, snap-store, ubuntu-desktop-installer, subiquity.
+* Individual analysis pending: `chromium`, `cyphesis-cpp`, `ember`, `firefox`, `freeshow`, `gnome-3-38-2004`, `gtk-common-themes`, `lxd`, `snapcraft`, `snapd-desktop-integration`, `snap-store`, `ubuntu-desktop-installer`, `subiquity`.
 
 * Snaps compliant: TBC
 
@@ -307,13 +307,13 @@ This is not currently the case, although the required metadata may be available 
 
 #### Principle 8: a public issue/bug tracker is available
 
-* Individual analysis pending: chromium, cyphesis-cpp, ember, firefox, freeshow, gnome-3-38-2004, gtk-common-themes, lxd, snapcraft, snapd-desktop-integration, snap-store, ubuntu-desktop-installer, subiquity.
+* Individual analysis pending: `chromium`, `cyphesis-cpp`, `ember`, `firefox`, `freeshow`, `gnome-3-38-2004`, `gtk-common-themes`, `lxd`, `snapcraft`, `snapd-desktop-integration`, `snap-store`, `ubuntu-desktop-installer`, `subiquity`.
 
 * Snaps compliant: TBC
 
 * Snaps not compliant: TBC
 
-### Unresolved Issues
+### Unresolved issues
 
 The following issues are relevant to this document, and probably contradict this policy. In order to make progress, we will accept these for now, and hope to find a suitable resolution later.
 
@@ -334,11 +334,11 @@ This identifies a similar issue in two different software components:
 
 Sebastian Bacher asked:
 
-*Ubuntu has a restricted section for things like nvidia drivers which are provided by default and non dfsg-free, we should probably have an equivalent exception for snaps?*
+*Ubuntu has a restricted section for things like NVIDIA drivers which are provided by default and non dfsg-free, we should probably have an equivalent exception for snaps?*
 
 Robie Basak responded:
 
-*AIUI, these always require explicit user opt-in. Eg. the 22.04.1 installer says "Install third-party software for graphics and Wi-Fi hardware and additional media formats. This software is subject to license terms included with its documentation. Some is proprietary."*
+*As I understand it, these always require explicit user opt-in. E.g. the 22.04.1 installer says "Install third-party software for graphics and Wi-Fi hardware and additional media formats. This software is subject to license terms included with its documentation. Some is proprietary."*
 
 *I think this puts the restricted archive component out of the scope of these requirements, based on the user's explicit informed consent that matches the requirement in the "Out of Scope" section of this document.*
 
@@ -350,15 +350,15 @@ However, on checking, the restricted and multiverse archive components are enabl
 
 Sebastian Bacher asked, in reference to the requirement to make publicly available the sources and build logs, in respect of snaps:
 
-*We don't have logs compliant with those requirements today afaik, build&#8203;-snapcraft.io doesn't publish build history and logs and launchpad only lists the 10 most recent builds entries and has no UI to browser older items. Was there any discussion started with the launchpad team about the topic?*
+*We don't have logs compliant with those requirements today as far as I know, `build.snapcraft.io` doesn't publish build history and logs and Launchpad-only lists the 10 most recent builds entries and has no UI to browse older items. Was there any discussion started with the Launchpad team about the topic?* (Note: `build.snapcraft.io` has been deprecated: [We are changing the way you build snaps from GitHub repositories](https://snapcraft.io/blog/we-are-changing-the-way-you-build-snaps-from-github-repos).)
 
 Robie: yes, I did consult with the Snap Store team that this should in principle be fixed at the Snap Store end. The implementation of this requirement in the case of snaps will remain incomplete for now, pending the necessary engineering work. But this document initially defines that our goal as a project is that this will be done.
 
-### Other Feedback
+### Other feedback
 
 There was much valuable feedback received, and this led to many iterations of this document. However some feedback was considered out of scope or deliberately not acted upon. To avoid forgetting about it, these are documented here.
 
 #### Deferred for possible implementation in the future
 
 * William Grant asked, in the context of requiring public sources and build logs to be available: *Do we want to require debug symbols too?*
-* @vanvugt [suggested](https://discourse.ubuntu.com/t/technical-board-feedback-requested-draft-policy-on-third-party-software-sources-included-by-ubuntu/46849/4?u=rbasak) requiring support for automated crash dumps and frame pointers
+* Daniel van Vugt [suggested](https://discourse.ubuntu.com/t/technical-board-feedback-requested-draft-policy-on-third-party-software-sources-included-by-ubuntu/46849/4?u=rbasak) requiring support for automated crash dumps and frame pointers