We've long acknowledged that the SRU documentation has outgrown its
(mostly) single wiki page, and that one of the reasons uploads are
mismatching SRU team expectations more frequently than they should is
that the documentation is lacking.
I've been driving a significant evolution into more detailed, refactored
documentation, with the rest of the SRU team reviewing my drafts. We
think the replacement[2] is now an improvement over the current wiki
docs, so I'm switching it over today.
This does not reflect any change to SRU process or SRU team
expectations, but is rather an attempt to better document our existing
expectations and make it easier for Ubuntu developers to prepare SRUs
that meet these expectations first time.
The new documentation isn't intended to be read cover to cover. It
follows Diátaxis[1]. If you're already familiar with SRUs, then it
should be sufficient for you to use the How-to section for
checklist-style steps to follow and Reference section for the bug
template, links to status reports and suchlike, without the need to look
deeper. Extensive cross-references are provided should you need more
details.
You can find the new documentation here[3]:
https://canonical-sru-docs.readthedocs-hosted.com/en/latest/
I will edit the existing wiki to link to the new documentation instead,
with the intention of preserving the fragment URIs using "deep links" as
much as possible. I've already done a pass over the wiki to ensure that
everything within it is incoporated into the replacement documentation.
The "Documentation for Special Cases" section isn't yet migrated. Until
that is done, please continue using the wiki for that section. Apart
from that, new changes to SRU documentation should be made in the new
documentation and not in the wiki.
The new documentation is still a work in progress, and you'll notice
notes within it in areas that still need cleaning up or expanding upon.
But, with the agreement of the SRU team, I'm publishing it now anyway
since it is an improvement over the existing wiki documentation.
Sources for the new documentation are available at the new Launchpad
project[4]. Merge proposals against the repository to improve the
documentation would be much appreciated!
In case you need to see the edit history of the old wiki, I have taken
care to preserve that as best as I can in the new git repository
history.
I've also made available the edit history of the replacement
documentation[5].
Thanks to Robert Krátký for his help with setting up the new
documentation, and to the whole SRU team for the multiple review rounds!
Robie
[1]: https://diataxis.fr/
[2]: https://canonical-sru-docs.readthedocs-hosted.com/en/latest/
[3]: I'm not sure if this is going to be the final URL or not. The
"canonical-" prefix is because it's hosted by Canonical's RTD account;
Ubuntu's usual governance system still applies!
[4]: https://launchpad.net/sru-docs
[5]: https://docs.google.com/document/d/1akt_aLrDc0bArj75NkoCOh-UJN7OW006470HE3l-_7E/edit
