Repository navigation
Conversation
cpaelzer
requested review from
RAOF,
basak,
enr0n,
julian-klode,
msuchane,
panlinux,
rkratky,
s-makin and
tjaalton
as code owners
September 24, 2026 06:48
cpaelzer
force-pushed
the
improve-SRU-test-posture-and-consumption-by-navigation
branch
from
September 29, 2026 13:28
dd51c84 to
e88ead4
Compare
Collaborator
Author
|
FYI - I created #816 to separate the test step preference from all the navigation changes which may be more complex to discuss. Due to that I also re-based this PR here onto latest main and took out the test preference changes Furthermore I acknowledge that you might feel "why another nav system" which is why I asked @s-makin to please document the three existing patterns in https://ubuntu.com/project/docs/contributors/contribute-docs/ to make it clear that these (all three) have their separate use case and reasons to exist - depending on the case even all three at once. I hope that Sally can refer to that when she gets to do a review of this PR here. I hope that helps you to consider this PR as I truly think this will help readers/users of these docs. |
cpaelzer
changed the title
Collaborator
Specifically: https://ubuntu.com/project/docs/contributors/contribute-docs/#organization-principles |
Collaborator
Author
Thank you @panlinux for pointing to it, I did ask Sally to document which navigation styles we have to make it clear that I'm not free-styling here. Now the clock runs with changes making this non merge-able, I'd appreciate if the general approach could be reviewed and - if ok - approved. Then I can rebase once for the merge itself instead of playing daily catch up. Could you carry this to the next SRU meeting and let me know if I should join anything/anywhere to discuss it so it does not stall too much more? |
Collaborator
Author
|
As I was afraid I had to rebase this due to the conflicts that general development on the docs caused. Obviously I believe in this helping the readers (or I'd not have worked on and proposed it), after all it was inspired by questions of my mentees and some other occasional contacts all struggling about finding one SRU element from the others. I know it is a larger change, but could I ask to try to not let this hang and instead either:
P.S. I have seen the linkcheck fail, but that is not me - it is autopkgtest limiting requests and the link check asking it too often :-/ |
cpaelzer
force-pushed
the
improve-SRU-test-posture-and-consumption-by-navigation
branch
from
October 15, 2026 06:29
e88ead4 to
4b467d7
Compare
enr0n
approved these changes
Oct 15, 2026
enr0n
left a comment
enr0n
left a comment
Collaborator
There was a problem hiding this comment.
I agree that we don't want to keep this hanging, and I do believe it is an improvement to the current situation. +1 from me.
Just going to see if the clanker finds anything noteworthy.
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The documentation changes are straightforward, with only a minor navigation-duplication issue remaining.
1 open finding
What changed in this PR
Improves navigation through Ubuntu’s SRU documentation while retaining its topic-based organization.
Changes:
- Adds shared series navigation across SRU guides and package exceptions.
- Consolidates related guidance and redirects removed pages.
- Updates entry points, cross-references, and navigation styling.
| File | Description |
|---|---|
| docs/who-makes-ubuntu/roles/SRU/index.rst | Adds series navigation. |
| docs/SRU/stable-release-updates.rst | Expands overview and guide navigation. |
| docs/SRU/reference/status.rst | Explains status reports and adds navigation. |
| docs/SRU/reference/sru-verification.rst | Incorporates proposed-pocket setup. |
| docs/SRU/reference/special.rst | Adds series navigation. |
| docs/SRU/reference/rota.rst | Adds series navigation. |
| docs/SRU/reference/requirements.rst | Adds navigation and removes incorrect link. |
| docs/SRU/reference/package-specific.rst | Adds navigation and corrects policy reference. |
| docs/SRU/reference/index.rst | Updates navigation for merged verification guide. |
| docs/SRU/reference/historical-removals.rst | Adds series navigation. |
| docs/SRU/reference/exception-wslu-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-walinuxagent-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Virtualbox-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Valkey-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-UbuntuImage-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-UbuntuDevTools-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-UbuntuAdvantageTools-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Squid-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Sosreport-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-SnapdGlib-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Snapd-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Snapcraft-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-rax-nova-agent-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-PostgreSQL-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Postfix-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-OpenVPN-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-OpenVMTools-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-OpenStack-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-OpenLDAP-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-OpenJDK-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-OEMMeta-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-NVidia-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Netplan-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-multipath-tools-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-MariaDB-Galera-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Landscape-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Kernel-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Intel-Graphics-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-HAProxy-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Grub-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-google-osconfig-agent-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-google-guest-agent-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-google-compute-engine-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-google-compute-engine-oslogin-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-GNOME-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-gce-compute-image-packages-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-firmware-updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-ec2-hibinit-agent-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-DPDK-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Docker-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Curtin-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-CrashMakedumpfile-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Cloudinit-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Certbot-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Bind9-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Azure-VM-Utils-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Azure-Proxy-Agent-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-autopkgtest-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/exception-Apt-Updates.rst | Adds exception navigation. |
| docs/SRU/reference/enable-proposed.rst | Removes page merged into verification. |
| docs/SRU/reference/bug-template.rst | Adds series navigation. |
| docs/SRU/internal.rst | Adds reference anchor and navigation. |
| docs/SRU/howto/standard.rst | Incorporates release guidance. |
| docs/SRU/howto/special.rst | Incorporates preparation guidance. |
| docs/SRU/howto/release.rst | Removes page merged into standard guide. |
| docs/SRU/howto/regression.rst | Adds series navigation. |
| docs/SRU/howto/prepare-special.rst | Removes page merged into special guide. |
| docs/SRU/howto/phasing.rst | Adds series navigation. |
| docs/SRU/howto/introduction-to-sru.rst | Removes separate introductory page. |
| docs/SRU/howto/index.rst | Simplifies guide navigation. |
| docs/SRU/howto/contact.rst | Adds series navigation. |
| docs/SRU/howto/common-issues.rst | Adds series navigation. |
| docs/SRU/howto/autopkgtest-failure.rst | Adds series navigation. |
| docs/SRU/explanation/standard-processes.rst | Links to shared phasing explanation. |
| docs/SRU/explanation/requirements.rst | Consolidates requirements and rationale. |
| docs/SRU/explanation/principles.rst | Adds series navigation. |
| docs/SRU/explanation/pipeline.rst | Adds series navigation. |
| docs/SRU/explanation/non-standard-processes.rst | Adds series navigation. |
| docs/SRU/explanation/further-requirements.rst | Removes merged rationale page. |
| docs/SRU/_sru-series.rst | Defines shared topic navigation. |
| docs/SRU/_sru-series-exception.rst | Defines exception navigation wrapper. |
| docs/redirects.txt | Redirects consolidated and legacy pages. |
| docs/maintainers/index.md | Links to the SRU overview. |
| docs/contributors/index.md | Links to consolidated SRU documentation. |
| docs/conf.py | Excludes series includes as standalone pages. |
| docs/_static/custom_styles.css | Marks exception parent-section links. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The introduction howto almost entirely duplicated content that is authoritative elsewhere (acceptance criteria, pipeline, verification, phasing, regression handling, removal rules). Keep its audience-oriented "when is SRU necessary" list on the section landing page, so there is a single entry point answering what SRUs are and when they apply. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
"Get an SRU released from proposed" is the tail of the standard process and was already covered by its steps 9-11. Keeping it in one page matches how drivers experience the lifecycle. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
"Prepare a special type of SRU" was a 24-line router adding a hop before the actual guidance, and its target shared a title with the reference page on special SRU types. One page per task family, with the routing steps as its introduction. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Enabling the -proposed pocket is step 2 of SRU verification; the procedure is not actionable without it. Also fixes the duplicated step numbering in the test plan. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Both pages explained the reasoning behind SRU requirements: one the three core requirements, the other their preconditions and the expectations for documentation and test plans. Merging removes a confusingly similar title pair and one hop between related content; all sub-anchors survive on the merged page. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Trim the phasing explanation to a summary linking the phased-updates concept page, which already described the mechanism verbatim. Fix the clamav example that linked to the unrelated ec2-hibinit-agent exception, and the dangling #When anchor in the package-specific notes that predates the wiki migration. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Restore the four-space list-item continuation that step 11 of the standard-SRU howto relies on for its multi-line references, and fix too-short heading underlines in the merged verification reference and in the trimmed phasing section. Sphinx emits warnings for both, and the docs build fails on warnings. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Follow the pattern of the MIR series: every page carries a compact navigation admonition at the top that ties the topic together and shows where the current page sits in it. Package exception pages use a variant that marks them as children of the package-specific notes hub instead of listing all 49 of them in the header. The roles page in who-makes-ubuntu joins the series so readers arriving there find their way into the guides. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
The howto index hung under Contributors, so the SRU section navigation never showed any howto guidance, and its index shared the title of the section landing page. Give the howto index to the SRU landing page toctree (a document can only live in one toctree) and link it from Contributors by prose instead. Move the stable-release-updates label to the landing page so references that mean "the SRU process" land there instead of on a bare howto index. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
maintainers/SRU contained only a glob index and an empty "How to review an SRU" stub. The reviewing procedure is documented in the SRU internal docs, so link maintainers directly to the SRU documentation instead of dead-ending them on a stub, and route old stub URLs there. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
The _*series* files are navigation headers that the pages of their article series include (MIR, DMB, SRU). Sphinx also read them as standalone documents and rendered them as hidden pages containing nothing but the header, complete with sitemap and search entries. Exclude the naming pattern from document discovery; include directives read these files from disk and are unaffected. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
The merged pages jump straight into the content of the first absorbed page. Lead each of them with a short roadmap instead: name the parts of the page and link to their sections, so readers see what the page covers before the detail starts. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
The header filled most of a full-HD viewport, and several bullets
merely restated their link target ("SRU bug template - The SRU bug
template"). Pack the sixteen links into eight bullets by folding
secondary links into their lead entry's description, as the DMB
series header does, and rewrite every description to say what the
target actually covers. Cuts the rendered height by about forty
percent without dropping a link.
Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
The "(in this section)" hint on the package exception pages was plain static text while its sibling marker "(in this article)" is generated by CSS in a grey italic style. Give the exception admonition its own class and render the marker the same way, so both hints share one visual language. The two series partials now differ only in their class line; the CSS skips the link on the package-specific notes page itself, where the existing in-this- article rule already applies. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
The page jumped straight into a list of report links with nothing saying what they are for. Explain that the reports are part of performing an SRU, that they track ongoing cases as they flow from sponsorship to release and phasing, and that they are the practical status check for the SRU pipeline. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
The status pages belong with performing an SRU rather than with the package-specific exceptions, so give them their own Perform entry next to the verification they support. Fold the team links into Understand and merge Troubleshoot into Reference, cutting the header from five group labels to three. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
The exception variant duplicated the whole series header with a single changed class line, so every wording edit had to be made twice and could drift. Reduce it to a shim that only attaches the marker class and includes the shared header; rst-class merges the class onto the admonition that follows it. Content is single-sourced now while exception pages keep their in-this-section attribution. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Now that the combined articles, the infrastructure for the headers and the few extra paragraphs (most is only moved) is in place adjust the header to be most useful to a user of the project documentation looking after anything in regard to the SRU process. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Changes in the included page let to including the wrong content, change this from an offset that might be affected at any change to refer to content as it is done in all other cases and would trigger a warning if that was not found. Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
cpaelzer
force-pushed
the
improve-SRU-test-posture-and-consumption-by-navigation
branch
from
October 16, 2026 08:31
31c3ce8 to
dee41b3
Compare
Collaborator
|
The removed files check is throwing a failure but the files it picked up haven't actually been removed (either in this PR or in main). Suggesting ignoring the failure. |
Collaborator
Sounds good. If you are happy with it, can you please add your approval? |
s-makin
approved these changes
Oct 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.
Description
Hi,
I always liked the SRU docs, and even more after the big rework by @basak.
But we knew it had its weaknesses, it was better than the old and thereby fine.
But I've used (e.g. fetching the template), teached (training my mentees) and guided (helped people that looked for or misunderstood one or the other thing in chat and discussions). And it is time to propose a change to improve on the weak spots.
I initially only wanted to ensure a better clarity that for testing an SRU case no one "wants" or "prefers" a prosa test plan. Sure it is the ultimate fallback, but in several occasions it was clear that an autopkgtest would be better (tests automatically, and will re-run in the future) and in other cases a script would have helped to avoid misunderstandings.
I was done with knowing that but not seeing it being asked for. To be clear, I understand there are cases that can not do more than describing it, but at least suggest bringing better tests. While pondering about the placement I realized that after the initial study users likely only every read/copy/paste the template, so to remind them this is the right place to mention that.
While working on that I could not stop anymore. Way too often in mentoring or chats did I need to say "yes I know it is hard to find" and "you almost found the right one, it is here which is ... hard to reach" and so on. All the content was there but it was so scattered that it became less helpful than it could be. Splitting it into topics has benefits and drawbacks over a single page that has it all, depending how someone consumes the documentation the navigation scheme is better in one or the other way. I have faced the same in the MIR and DMB related documentation, and there after checking with the authors and looking at alternatives we found a great option. Keep the nav scheme (how things are sorted in the nav bar per diataxis or even something else) as-is, but at the same time provide more topic-bound headers that describe an article series containing all about this topic. This helps a lot to move from one page to another while staying in the topic. So I decided I need to add this benefit to the SRU docs as well. For that I first studied what could be reasonably grouped (the few pages where splitting might have gone too far) and then found some pages which ended up listing facts without any paragraph explaining what this is about (like the status check page was). I merged and extended those to be better. Then I created and iterated on the article-series and all the things I needed to get that to be nice and working well.
At the end there is not much content change (only the new test suggestion and a few explanations what a page is talking about), but a lot of movement.
I hope you agree it is much more consumable now and help me to land this,
thanks in advance,
Christian
P.S. I found two more things along the way - the header includes got rendered as unlinked uselsss pages, that is blocked in docs/conf.py now and there was an empty stub in docs/maintainers/SRU saying nothing which I now pointed to the meaningful content.