Refactor docs structure#2
Merged
danieltoader-canonical merged 4 commits intoJun 16, 2026
Merged
Conversation
danieltoader-canonical
requested review from
PrinsonF77,
kunalmohan-work and
trollLemon
Contributor
There was a problem hiding this comment.
Pull request overview
Refactors the documentation information architecture from legacy livepatch* paths into distinct top-level client/, server/, support/, release-notes/, and contribute/ sections, aligning content with a deeper Diátaxis-style structure and preserving legacy URLs via redirects.
Changes:
- Introduces new section landing pages (client/server/support/release-notes/contribute) and adds new sub-index pages (e.g., platform/auth/telemetry/patch-management).
- Updates MyST targets/anchors and rewrites cross-page links to the new paths.
- Adds/expands redirects to keep old URLs working after the restructure, and removes legacy index pages.
Reviewed changes
Copilot reviewed 128 out of 128 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Simplifies top-level documentation list to client + server. |
| CHANGELOG.md | Documents the restructure as a 1.0.0 release entry. |
| docs/index.md | Updates product overview links and adds toctrees for new sections. |
| docs/redirects.txt | Adds extensive redirects mapping legacy paths to new structure. |
| docs/contribute/index.md | Adds contribution guidance and an AI usage policy page. |
| docs/support/index.md | Adds a Support section landing page and toctree. |
| docs/support/report-bugs.md | Renames MyST target for the support bug reporting page. |
| docs/support/get-more-help.md | Renames MyST target and updates Ubuntu Pro link. |
| docs/release-notes/index.md | Adds a release-notes landing page for client/server. |
| docs/release-notes/client/index.md | Adds a client release notes landing page. |
| docs/release-notes/server/index.md | Updates server release-notes metadata/target naming. |
| docs/client/index.md | Renames client home target and updates section links. |
| docs/client/reference/index.md | Adds new client reference landing page + section links. |
| docs/client/reference/platform/index.md | Adds client platform reference index (kernels/config/arch). |
| docs/client/reference/platform/supported-kernels.md | Updates MyST target and link to new troubleshooting path. |
| docs/client/reference/platform/configuration-options.md | Updates MyST target and how-to link path. |
| docs/client/reference/platform/which-are-the-supported-architectures.md | Updates MyST target for architectures page. |
| docs/client/reference/networking/index.md | Adds client networking reference index. |
| docs/client/reference/networking/network-requirements.md | Updates MyST target. |
| docs/client/reference/networking/content-caching.md | Updates MyST target. |
| docs/client/reference/networking/data-sent.md | Updates MyST target. |
| docs/client/reference/patches/index.md | Adds client patches reference index. |
| docs/client/reference/patches/patch-installation.md | Updates MyST target. |
| docs/client/reference/patches/patch-lifecycle.md | Updates MyST target and internal links. |
| docs/client/reference/patches/patch-security.md | Updates MyST target and internal links. |
| docs/client/explanation/index.md | Adds client explanation landing page (architecture/security/troubleshooting). |
| docs/client/explanation/architecture/index.md | Adds client architecture explanation index. |
| docs/client/explanation/architecture/how-livepatching-works.md | Updates MyST target. |
| docs/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md | Updates MyST target and content links. |
| docs/client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md | Updates MyST target. |
| docs/client/explanation/architecture/what-are-livepatch-tiers.md | Updates MyST target and server link path. |
| docs/client/explanation/architecture/when-should-i-expect-new-updates.md | Updates MyST target. |
| docs/client/explanation/security/index.md | Adds client security explanation index. |
| docs/client/explanation/security/how-cves-are-rated.md | Updates MyST target. |
| docs/client/explanation/security/security-overview.md | Updates MyST target and cross-links. |
| docs/client/explanation/security/security-lifecycle.md | Updates MyST target. |
| docs/client/explanation/security/livepatch-security-notices.md | Updates MyST target. |
| docs/client/explanation/troubleshooting/index.md | Adds client troubleshooting explanation index. |
| docs/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md | Updates MyST target and supported-kernels links. |
| docs/client/explanation/troubleshooting/service-access-problem.md | Updates MyST target and proxy link. |
| docs/client/explanation/troubleshooting/why-are-there-missing-patches.md | Adds moved “missing patches” explanation page under troubleshooting. |
| docs/client/explanation/troubleshooting/what-happens-when-a-problem-cannot-be-patched.md | Updates MyST target. |
| docs/client/explanation/troubleshooting/do-i-need-to-reboot.md | Updates MyST target. |
| docs/client/explanation/troubleshooting/what-is-patch-cut-off-date.md | Updates MyST target. |
| docs/client/how-to-guides/index.md | Adds client how-to landing page and section links. |
| docs/client/how-to-guides/installation/index.md | Adds client installation how-to index. |
| docs/client/how-to-guides/installation/enable-client.md | Updates MyST target and normalizes command examples. |
| docs/client/how-to-guides/installation/enable-client-on-ubuntu-core.md | Updates MyST target. |
| docs/client/how-to-guides/installation/disable-client.md | Updates MyST target. |
| docs/client/how-to-guides/installation/disable-livepatch-during-startup.md | Updates MyST target and cross-links. |
| docs/client/how-to-guides/configuration/index.md | Adds client configuration how-to index. |
| docs/client/how-to-guides/configuration/configure-livepatch-client.md | Updates MyST target. |
| docs/client/how-to-guides/configuration/configure-proxy.md | Updates MyST target. |
| docs/client/how-to-guides/configuration/use-patch-cut-off-date.md | Updates MyST target, links, and command examples. |
| docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md | Updates MyST target and paths referenced in cloud-init examples. |
| docs/client/how-to-guides/operations/index.md | Adds client operations how-to index. |
| docs/client/how-to-guides/operations/check-client-status.md | Updates MyST target. |
| docs/client/how-to-guides/security/index.md | Adds client security how-to index. |
| docs/client/how-to-guides/security/securely-configure-and-operate-the-client.md | Updates MyST target and cross-links. |
| docs/client/how-to-guides/security/securely-decommission-the-client.md | Updates MyST target. |
| docs/client/how-to-guides/security/report-client-vulnerability.md | Updates MyST target. |
| docs/server/index.md | Renames server home target and updates section links to new indexes. |
| docs/server/tutorial/index.md | Adds server tutorial landing page and toctree. |
| docs/server/tutorial/livepatch-and-lxd.md | Updates MyST target and rewrites links to new server structure. |
| docs/server/tutorial/livepatch-and-microk8s.md | Updates MyST target and rewrites links to new server structure. |
| docs/server/tutorial/airgapped-livepatch-and-microk8s.md | Updates MyST target/title and rewrites links + command examples. |
| docs/server/tutorial/airgapped-livepatch-and-snap.md | Updates MyST target/title and rewrites links + command examples. |
| docs/server/explanation/index.md | Adds server explanation landing page (architecture/observability). |
| docs/server/explanation/architecture/index.md | Adds server architecture explanation index. |
| docs/server/explanation/architecture/security-overview.md | Updates MyST target and rewrites links to new reference/how-to paths. |
| docs/server/explanation/architecture/security-lifecycle.md | Updates MyST target. |
| docs/server/explanation/architecture/access-control.md | Updates MyST target and rewrites cross-links. |
| docs/server/explanation/observability/index.md | Adds server observability explanation index. |
| docs/server/explanation/observability/logging-and-monitoring.md | Updates MyST target and rewrites how-to link. |
| docs/server/how-to-guides/index.md | Adds server how-to landing page and section links. |
| docs/server/how-to-guides/deployment/index.md | Adds deployment how-to index with links to sub-guides. |
| docs/server/how-to-guides/deployment/deploy-via-juju.md | Updates MyST target and rewrites links to new structure. |
| docs/server/how-to-guides/deployment/deploy-via-snap.md | Updates MyST target and normalizes command examples. |
| docs/server/how-to-guides/deployment/deploy-cve-service-via-snap.md | Updates MyST target. |
| docs/server/how-to-guides/deployment/upgrade-a-deployment.md | Updates MyST target. |
| docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md | Updates MyST targets and rewrites links + example paths. |
| docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md | Updates MyST target. |
| docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md | Updates MyST target. |
| docs/server/how-to-guides/deployment/public-clouds/index.md | Updates MyST target and refactors cloud-init example paths/toctree entries. |
| docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md | Updates MyST target and refactors cloud-init example paths. |
| docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md | Updates MyST target and refactors cloud-init example paths. |
| docs/server/how-to-guides/patch-management/index.md | Adds patch-management how-to index. |
| docs/server/how-to-guides/patch-management/fetch-patches.md | Updates MyST target and rewrites configuration link. |
| docs/server/how-to-guides/patch-management/use-the-patch-downloader-tool.md | Updates MyST target and rewrites links + command examples. |
| docs/server/how-to-guides/patch-management/configure-proxy-for-fetching-patches.md | Updates MyST target and rewrites links. |
| docs/server/how-to-guides/patch-management/chain-livepatch-servers.md | Updates MyST target and rewrites links. |
| docs/server/how-to-guides/operations/index.md | Adds server operations how-to index. |
| docs/server/how-to-guides/operations/manage-fleet-of-machines.md | Updates MyST target. |
| docs/server/how-to-guides/operations/generate-patch-health-report.md | Updates MyST target. |
| docs/server/how-to-guides/operations/scale-out.md | Updates MyST target. |
| docs/server/how-to-guides/operations/configure-logging-and-monitoring.md | Updates MyST targets and rewrites explanation link. |
| docs/server/how-to-guides/operations/decommission.md | Updates MyST target and edits filesystem patch path guidance. |
| docs/server/how-to-guides/operations/use-livepatch-client-with-on-prem-server.md | Updates MyST target and rewrites reference link. |
| docs/server/how-to-guides/security/index.md | Adds server security how-to index. |
| docs/server/how-to-guides/security/setup-tls.md | Updates MyST targets and rewrites client proxy link. |
| docs/server/how-to-guides/security/setup-administration-tool.md | Updates MyST targets. |
| docs/server/how-to-guides/security/harden-your-deployment.md | Updates MyST target and rewrites links across new structure. |
| docs/server/how-to-guides/security/report-server-vulnerabilities.md | Updates MyST target. |
| docs/server/reference/index.md | Adds server reference landing page and section links. |
| docs/server/reference/platform/index.md | Adds server platform reference index. |
| docs/server/reference/platform/configuration.md | Updates MyST target and rewrites links to new structure. |
| docs/server/reference/platform/resource-requirements.md | Updates MyST target. |
| docs/server/reference/platform/network-access.md | Updates MyST target. |
| docs/server/reference/authentication/index.md | Adds authentication reference index. |
| docs/server/reference/authentication/authentication.md | Updates MyST targets and rewrites internal anchor links. |
| docs/server/reference/patch-management/index.md | Adds patch-management reference index. |
| docs/server/reference/patch-management/patch-management.md | Updates MyST target. |
| docs/server/reference/patch-management/patch-sync-filters.md | Updates MyST target and rewrites config link. |
| docs/server/reference/patch-storage/index.md | Updates MyST target and rewrites links to new structure. |
| docs/server/reference/patch-storage/use-s3-for-patch-storage.md | Updates MyST target and rewrites config links. |
| docs/server/reference/telemetry/index.md | Adds telemetry reference index. |
| docs/server/reference/telemetry/data-sent.md | Updates MyST target. |
| docs/server/reference/telemetry/machine-reports.md | Updates MyST target and rewrites cross-links. |
| docs/livepatch/reference/index.md | Removes legacy client reference index (moved under docs/client/reference/). |
| docs/livepatch/how-to-guides/index.md | Removes legacy client how-to index (moved under docs/client/how-to-guides/). |
| docs/livepatch/explanation/index.md | Removes legacy client explanation index (moved under docs/client/explanation/). |
| docs/livepatch/explanation/why-are-there-missing-patches.md | Removes legacy page (moved under client troubleshooting). |
| docs/livepatch_server_on_public_clouds/index.md | Removes legacy public-cloud server index (moved under server deployment/public-clouds). |
| docs/livepatch_server_on_public_clouds/how-to-guides/index.md | Removes legacy public-cloud how-to index (moved under server deployment/public-clouds). |
| docs/livepatch_on_prem/tutorial/index.md | Removes legacy server tutorial index (moved under docs/server/tutorial/). |
| docs/livepatch_on_prem/reference/index.md | Removes legacy server reference index (moved under docs/server/reference/). |
| docs/livepatch_on_prem/how-to-guides/index.md | Removes legacy server how-to index (moved under docs/server/how-to-guides/). |
| docs/livepatch_on_prem/explanation/index.md | Removes legacy server explanation index (moved under docs/server/explanation/). |
Comments suppressed due to low confidence (7)
docs/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md:12
- This link to the upstream kernel livepatch documentation is malformed: it points to
Documentation/client/livepatch.rst, which doesn't exist in the Linux kernel tree. It should point toDocumentation/livepatch/livepatch.rst.
docs/server/reference/patch-storage/use-s3-for-patch-storage.md:26 - The URL template example has a malformed bucket placeholder and misspells
{filename}as{filaname}, which makes the example unusable as-is.
docs/server/tutorial/livepatch-and-lxd.md:159 - This S3 URL template example uses a hard-coded path segment
client/patches/, which looks like an accidental rename and is unlikely to match a real bucket layout. Use an explicit bucket placeholder (or your real bucket name) in the example.
docs/server/how-to-guides/deployment/public-clouds/index.md:87 - In this cloud-init snippet, the
snap setcommand continuation is broken: there is a\followed by a space onlp.server.server-address=...(so the newline is not escaped), and the# optionalcomment line sits in the middle of the continued command, which will comment-out the remainder and leave the followinglp.cve-*lines as separate (invalid) shell commands.
docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md:10 - This AWS page later says it deploys on Azure, which is incorrect and likely a copy/paste error.
docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md:70 - The URL template placeholder is misspelled as
{filaname}; it should be{filename}to match how the server expands the template.
docs/server/how-to-guides/operations/decommission.md:59 - The default filesystem patch directory is given as
/var/lib/client/patches, which looks like an accidental path rename during the docs restructure. Instead of hard-coding an unverified default, refer to the configuredpatch-storage.filesystem-path.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
danieltoader-canonical
force-pushed
the
refactor-docs-structure
branch
from
8818efb to
859b75c
Compare
danieltoader-canonical
force-pushed
the
refactor-docs-structure
branch
from
859b75c to
7262c0d
Compare
5 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 128 out of 128 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (10)
docs/client/index.md:20
- This markdown table row is missing leading/trailing
|, which will break table rendering for the “Reference” entry.
docs/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md:12 - The upstream Linux documentation link looks incorrect (
Documentation/client/livepatch.rstdoes not exist in torvalds/linux). It should point toDocumentation/livepatch/livepatch.rst.
docs/server/how-to-guides/operations/decommission.md:59 - The documented default filesystem patch directory appears incorrect. Elsewhere in the server docs, the default filesystem patch store path is
/var/snap/canonical-livepatch-server/common/patches.
docs/server/reference/patch-storage/use-s3-for-patch-storage.md:26 - The URL template placeholder is misspelled (
{filaname}), which would make this example incorrect for users configuring a URL template.
docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md:70 - The URL template placeholder is misspelled (
{filaname}), which would make this cloud-init example incorrect.
docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md:199 - The text says patches are stored in
/livepatchin the LXD container, but the example command pulls from/client. This makes the copy/paste instructions inconsistent.
docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md:203 - This move step refers to
common/client/*, but the preceding explanation (and comment) refer to a/livepatchdirectory. Keeping the directory name consistent avoids broken migration steps.
docs/server/how-to-guides/deployment/public-clouds/index.md:91 - This
snap set ... \example includes a commented line in the middle of a line-continued command. With the trailing\on the previous line, the# optional...comment will terminate the logical command line early and the CVE-related flags won’t be applied as shown.
docs/server/how-to-guides/deployment/public-clouds/index.md:54 - This server deployment cloud-init example stores secrets under
/etc/client/, which is likely misleading for a server install (and could conflict with the separate client cloud-init examples that use the same directory). Consider using a server-specific directory such as/etc/livepatch-server/(or keeping the previous/etc/livepatch/) consistently across the public-cloud deployment docs.
docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md:10 - This AWS guide currently says the deployment is “on Azure” a couple lines below, which is confusing in an AWS-specific page.
danieltoader-canonical
force-pushed
the
refactor-docs-structure
branch
3 times, most recently
from
660672b to
31297dc
Compare
erinecon
reviewed
Jun 15, 2026
erinecon
left a comment
erinecon
left a comment
There was a problem hiding this comment.
Hello, TA from Platform Engineering here 👋 I took a look at your proposed structure changes, and I think that it's a great improvement. The client/server components are clearly defined, and I think it's a good move to house your release notes and contributing guides in a dedicated toctree. Spotted some nits, but nothing concerning caught my eye!
I suggest that you turn on PR previews in the RTD backend for your project because it's a more convenient way to view changes made in a PR. (In case you don't already know, when you enable PR previews, RTD will build your docs based on your PR and then provide a link to the "preview" in the list of status checks.) Please let me know if you want any help turning them on!
danieltoader-canonical
force-pushed
the
refactor-docs-structure
branch
from
31297dc to
4880f3b
Compare
PrinsonF77
previously approved these changes
Jun 16, 2026
There was a problem hiding this comment.
LGTM. I think the new structure is much better than before. I have one comment though,
Since we are restructuring anyways, I wonder if it makes sense to move client/reference/networking/content-caching.md , client/reference/patches/patch-lifecycle.md and client/reference/patches/patch-installation.md into client/explanation. I think the content in these documents is more of an explanation than something that could be classified as a reference. WDYT?
Thank you!
danieltoader-canonical
dismissed stale reviews from trollLemon and PrinsonF77
via
7399370
danieltoader-canonical
force-pushed
the
refactor-docs-structure
branch
from
4880f3b to
7399370
Compare
Contributor
Author
done |
danieltoader-canonical
force-pushed
the
refactor-docs-structure
branch
from
7399370 to
36b54eb
Compare
PrinsonF77
approved these changes
Jun 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Before
After
(+)= newly createdindex.mdlanding page for a group.