Merge pull request #74 from canonical/feat/integrate-external-sru-docs

Integrate external sru docs

docs/.wordlist.txt

@@ -41,6 +41,9 @@ reStructuredText
 roadmap
 Roadmap
 RTD
+SRU
+SRUs
+StableReleaseUpdates
 subdirectories
 subtree
 subfolders

docs/custom_conf.py

@@ -169,8 +169,11 @@
     #'canonical.related-links',
     #'canonical.custom-rst-roles',
     #'canonical.terminal-output'
+    'sphinx.ext.intersphinx',
     ]
 
+intersphinx_mapping = {'sru': ('https://canonical-sru-docs.readthedocs-hosted.com/en/latest', None)}
+
 # Add custom required Python modules that must be added to the
 # .sphinx/requirements.txt file.
 # NOTE: The following modules are handled automatically and do not need to be

docs/explanation/_index.rst

@@ -18,7 +18,6 @@ knowledge and become better at packaging and development.
    launchpad
    sponsoring
    proposed-migrations
-   stable-release-updates
    debian-merges-and-syncs
    transitions
    backports

docs/explanation/debian-merges-and-syncs.rst

@@ -40,7 +40,7 @@ into the Debian package or :term:`Upstream` project and are no longer needed.
     must also request the respective freeze exception. 
 
     After the Final Release, you must follow the 
-    :doc:`/explanation/stable-release-updates` process. For additional details
+    :ref:`StableReleaseUpdates_Summary` process. For additional details
     about the freezes, see the :doc:`/explanation/development-process` article.
 
 Merges

docs/explanation/development-process.rst

@@ -312,9 +312,111 @@ the "Final Release", a representative of the team announces it on the
 Stable Release Updates
 ----------------------
 
-Released versions of Ubuntu are intended to be **stable**. This means that
-users should be able to rely on their behaviour remaining the same and
-therefore, updates are only released under particular circumstances.
-
-The dedicated :doc:`/explanation/stable-release-updates` article describes
-these criteria and the procedure for preparing such an update.
+After publication of an :term:`Ubuntu Stable Release`, there may be a need
+to update it or fix bugs. You can fix these newly-discovered bugs and make
+updates through a special process known as **Stable Release Update (SRU)**.
+
+The SRU process ensures that any changes made to a stable release are thoroughly
+vetted and tested before being made available to users. This is because many
+users rely on the stability of the stable release for their day-to-day
+operations, and any problem they experience with it can be disruptive.
+
+The following paragraphs intend to give you a brief introduction to the SRU
+process. See the dedicated :external+sru:ref:`Ubuntu SRU Documentation <home>`
+for more details about this process.
+
+When are SRUs necessary?
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+SRUs require great caution because they're automatically recommended to a large
+number of users. So, when you propose an update, there should be a strong
+rationale for it. Also, the update should present a low risk of
+:ref:`regressions <Regressions>`.
+
+You can propose an SRU in the following cases:
+
+- To fix high-impact bugs, including those that may directly cause security
+  vulnerabilities, severe regressions from the previous release, or
+  bugs that may directly cause loss of user data.
+- To adjust to changes in the environment, server protocols, or web services.
+  This ensures that Ubuntu remains compatible with evolving technologies.
+- For safe cases with low regression potential but high user experience 
+  improvement.
+- To introduce new features in :term:`LTS releases <LTS>`, usually under strict
+  conditions.
+- To update commercial software in the :term:`Canonical partner archive`.
+- To fix :term:`Failed to build from Source` issues.
+- To fix :term:`autopkgtest` failures, usually in conjunction with other
+  high-priority fixes.
+
+See also: :external+sru:doc:`SRU requirements <explanation/requirements>`
+
+Overview
+~~~~~~~~
+
+A typical SRU is performed like this:
+
+1. Ensure the bug is fixed in the :term:`current development release
+   <Current Release in Development>` and all subsequent supported releases to
+   ensure consistency across different Ubuntu versions, especially preventing
+   regressions when users upgrade to newer releases.
+#. Update the **existing** bug report detailing the Impact of the Bug, the Test
+   Plan to verify that the bug was fixed and highlight where problems could
+   occur.
+#. Get the package with the SRU patch into the upload queue.
+#. The SRU team then reviews from the unapproved queue. When the upload is
+   ready, the SRU team accepts the upload into the proposed pocket.
+#. Once the builds are ready, autopkgtest are triggered. Test the binaries
+   in the :term:`Ubuntu Archive` and follow up in the bug report with your 
+   verification results.
+#. The Ubuntu SRU Team evaluates the testing feedback and moves the package
+   into :ref:`updates <ArchivePockets_Updates>` after it passes a minimum ageing
+   period of 7 days without regressions.
+
+See :external+sru:ref:`how to perform an SRU <howto-perform-standard-sru>`.
+
+Verification
+^^^^^^^^^^^^
+
+Once the SRU team accepts the SRU into the proposed pocket, the SRU has to be
+verified by the reporter or affected users of the SRU bug in a software 
+environment that closely resembles the state after the SRU team copies the
+package to the updates pocket. Generally, this is with a system that's up
+to date with the release, security, and updates pockets. It shouldn't include
+other packages from the proposed or backports pocket, except commonly-installed
+packages built from the affected source package.
+
+Read :external+sru:doc:`more about this process <howto/release>`.
+
+SRU phasing
+^^^^^^^^^^^
+
+Once a package is released to the updates pocket, the update is then phased, 
+so it is gradually made available to expanding subsets of Ubuntu
+users.
+
+Read :external+sru:ref:`more about phasing <explanation-phasing>`.
+
+.. _Regressions:
+
+Regressions
+^^^^^^^^^^^
+
+Regressions are unintended negative consequences that updates introduce.
+They appear as new bugs or failures in previously well-functioning aspects of an 
+Ubuntu release. 
+
+Read :external+sru:ref:`more about regressions <explanation-regressions>`
+and :external+sru:ref:`how to handle regressions <howto-report-regression>`.
+
+Updates removal
+^^^^^^^^^^^^^^^
+
+If a bug fixed by an update doesn't get any testing or verification feedback for
+90 days, an automated "call for testing" comment is made on the bug report.
+If no testing occurs within an additional 15 days, totalling 105 days without any
+testing, the :term:`Stable Release Managers` removes the package from
+proposed and close the bug task as ``Won't Fix``.
+
+Also, updates are removed from proposed if they introduce a non-trivial
+regression.