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
signature.asc
Description: PGP signature
-- ubuntu-devel mailing list ubuntu-devel@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/ubuntu-devel
