From 76892e30b2bef1fca4456fb34cebd6ba4a7bad34 Mon Sep 17 00:00:00 2001 From: Shlomi Fish Date: Wed, 24 Jul 2024 12:02:37 +0300 Subject: [PATCH 1/6] Fix some English grammar; singular vs. plural inflections --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index dfa08bdf..2b9ec155 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -84,7 +84,7 @@ Ubuntu related software projects live. It is the place where bugs are tracked, source code is stored, tracked, get built, tested and much more. We will go into more detail in the following articles. For now, you can think of -Launchpad as a platforms like GitHub, GitLab or BitBucket. +Launchpad as a platform like GitHub, GitLab or BitBucket. IRC channels: ~~~~~~~~~~~~~ From 2205e27bec8cfe108b6097a70186b53df10fd632 Mon Sep 17 00:00:00 2001 From: activus-d Date: Mon, 12 Aug 2024 15:19:41 +0100 Subject: [PATCH 2/6] complete draft of Stable Release Updates (SRU) docs --- docs/explanation/releases.rst | 2 + docs/explanation/stable-release-updates.rst | 251 ++++++++++++++++++++ docs/reference/glossary.rst | 20 ++ docs/reuse/links.txt | 3 + 4 files changed, 276 insertions(+) diff --git a/docs/explanation/releases.rst b/docs/explanation/releases.rst index f88011d6..e336cc93 100644 --- a/docs/explanation/releases.rst +++ b/docs/explanation/releases.rst @@ -1,3 +1,5 @@ +.. _UbuntuReleases: + Ubuntu releases =============== diff --git a/docs/explanation/stable-release-updates.rst b/docs/explanation/stable-release-updates.rst index 7423edc4..479709f1 100644 --- a/docs/explanation/stable-release-updates.rst +++ b/docs/explanation/stable-release-updates.rst @@ -1,2 +1,253 @@ Stable Release Updates (SRU) ============================ + +After publication of the :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 :term:`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 of +the 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. + +When are Stable Release Updates necessary? +------------------------------------------ + +:term:`SRU` require great caution because they're automatically recommended to a very +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 `. + +You can propose an :term:`SRU` in the following cases: + +- To fix high-impact bugs, including those that may directly cause security + vulnerabilities, severe :ref:`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 `, 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. + +Low priority and Extended Security Maintenance (ESM) uploads +------------------------------------------------------------ + +Low-priority uploads, such as updates that fix bugs that don't affect users at +runtime, can be staged and bundled with a future :term:`SRU` or security update. + +For uploads to stable releases in their :term:`ESM` period, please prepare the +:term:`SRU` bug, then contact the :term:`Ubuntu ESM Team`. + +General requirements +-------------------- + +The general requirements for :term:`SRU` are designed to ensure the stability and +reliability of `Ubuntu releases `_. + +To prevent future :ref:`regressions ` when users upgrade to newer +Ubuntu versions, bugs should be fixed in the current development release before being +considered for an :term:`SRU`. + +Also, all subsequent supported releases should be fixed at the same time. This +ensures consistency across different Ubuntu versions. There are two exceptions to +this requirement. These exceptions apply only to bug fixes, not to hardware +enablement or new features: + +- When there are two current subsequent interim releases, fixing only the most + recent one is acceptable. This provides an upgrade path for users facing the + regression. +- When resources are limited, it's recommended but not a strict requirement to + fix all subsequent interim releases. If you're unable to fix all subsequent interim + releases, mark the bug tasks for those releases as ``Won't Fix`` and explicitly state + your intention not to fix them. The :term:`Ubuntu SRU Team` may accept this at their + discretion. Failure to communicate your intentions may result in additional review. + +SRU procedures +-------------- + +The following steps outline the process for submitting and managing an +:term:`SRU` in Ubuntu: + +1. Ensure that the bug is fixed in the current development release and that its + status is marked as ``Fix Released``. If the source package has changed names + between `releases `_, add the new source package as ``Also affecting`` + in the bug report. +2. Don't create a meta-bug with a title like ``Please SRU this`` instead of using + existing bug reports. This approach is redundant and lacks transparency for the + original bug reporters, whose feedback is important for verification. Such meta-bugs + will be invalidated by the :term:`Ubuntu SRU Team`, and the corresponding uploads + will be rejected from the queue. +3. Ensure that the bug report for the issue is public. If the bug has been reported + privately and can't be published, create a separate public bug report in + :term:`Launchpad` and transfer as much information as can be published. +4. Update the bug report with the following sections: + + - **Impact**: Explain the bug's effect on users and the reasons for backporting the + fix to the stable release. Optionally, include an explanation of how the upload + fixes the bug. + - **Test Plan**: Provide detailed instructions on how to reproduce the bug. These + instructions should be clear enough for someone unfamiliar with the package to + verify the fix. + - **Where Problems Could Occur**: Highlight potential areas where + :ref:`regressions ` might happen. This section should show that + potential risks have been considered. It should also provide additional test cases + to ensure there are no :ref:`regressions `. + +5. Prepare the :term:`SRU` upload, attach a ``debdiff`` to the bug, and request sponsorship + by subscribing ``ubuntu-sponsors`` to the bug. The upload should have the correct + release in the changelog header, a detailed and user-readable changelog and no + unrelated changes. If you can upload directly, use ``dput`` as normal. Once uploaded, + change the bug status to ``In Progress``. The status will be automatically updated to + ``Fix Committed`` once accepted into ``release-proposed``. +6. Ensure that the version number doesn't conflict with any future versions in other + Ubuntu releases. Also, include a reference to the :term:`SRU` bug number in the + changelog using the ``LP: #NNNNNN`` format, and only reference public bugs. +7. Once the :term:`Ubuntu SRU Team` reviews and accepts your upload, test the binaries + in the :term:`Ubuntu Archive` and follow up in the bug report with your verification + results. The :term:`Ubuntu SRU Team` will evaluate the testing feedback and move the + package into :ref:`updates ` after it passes a minimum aging + period of 7 days. +8. Subscribe to the bugmail of the package in :term:`Launchpad`, and monitor + :term:`Launchpad` for bug reports relating to the update for at least one week. If + you notice and confirm any regression, document it in a bug report marked with an + ``Importance: critical`` label. + +SRU phasing +-------------- + +Once a package is released to :ref:`updates `, +the update is then phased so that the update is gradually made available to expanding +subsets of Ubuntu users. + +Initially, the ``Phased-Update-Percentage`` is set to 10%, with a job running every 6 +hours to monitor for :ref:`regressions `. If no issues are detected, the +update percentage increments by 10% until it reaches 100%. So an update will become +fully phased after 54 hours. If a regression is found, the update is halted and the +``Phased-Update-Percentage`` is set to 0%. This will cause supported package managers +not to install the update. + +Investigating halted phased updates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To investigate why phasing stopped, use the phased updates report. + +When investigating an increased rate of crashes, focus on the crashes with the highest +number of occurrences. Examine the Occurrences table to determine if these crashes are +happening more frequently with the updated version of the package. If they are, +investigate the cause and address the crash in a follow-up :term:`SRU`. If not, +`contact the Ubuntu SRU Team`_ about overriding the crash report. + +For new errors, verify that they're indeed new by reviewing the versions table and checking +the ``Traceback`` or ``Stacktrace`` to determine if the error originates from the updated +package or an underlying library. If you believe the error wasn't caused by the update, +you can `contact the Ubuntu SRU Team`_ to override the crash. + +Overriding halted phased updates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Overriding halted phasing is similar to handling :term:`autopkgtest` failures.The phased +update machinery uses a file named ``phased-update-overrides.txt``, a simple CSV file +containing lines of the form ``source package``, ``version``, and ``$THING_TO_IGNORE``. + +``$THING_TO_IGNORE`` can either be an ``errors.ubuntu.com`` problem URL to ignore or +``increased-rate``. + +Verification +------------ + +:term:`SRU` verification should be done in a software environment that closely resembles +that which will exist after the package is copied to +:ref:`updates `. +Generally, this will be with a system that's up to date from +:ref:`release `, +:ref:`security `, and +:ref:`updates (explanation) `. +It shouldn't include other packages from +:ref:`proposed ` or +:ref:`backports `, +with one exception: other packages built from the affected source package must +be updated if they're generally installed. + +If the fix is sufficient, the :term:`SRU Verification Team` will update the bug status +to ``In Progress``, and change the ``verification-needed-$RELEASE`` tag to +``verification-failed-$RELEASE``. If the fix is sufficent, the :term:`SRU Verification Team` +will tag it as ``verification-done-$RELEASE``. + +If you encounter a regression in a package uploaded to +:ref:`proposed `, do the following: + +1. File a bug report describing the nature of the regression. +#. Tag the bug as ``regression-proposed``. +#. `Ask a bug supervisor`_ to target the bug to the appropriate `Ubuntu releases `_. +#. Follow up on the :term:`SRU` bug report referenced from the package changelog, pointing + to the new bug. If there is more than one bug in the :term:`SRU` changelog, follow up to + the bug that is most closely related to the regression. +#. Set the ``verification-failed-$RELEASE`` tag on the corresponding :term:`SRU` bug report. + +.. note:: + ``$RELEASE`` represents the release name of your upload. + +Packages accepted into :ref:`proposed ` automatically trigger +related :term:`autopkgtests `. + +If an :term:`SRU` upload triggers an :term:`autopkgtests ` regression, +the target package will not be released into :ref:`updates ` until +the issue is resolved. Once the tests are completed, the pending :term:`SRU` page provides +links to any failures noticed for the selected upload. It's the responsibility of the uploader +or the person performing update verification to ensure that the upload doesn't cause any +:ref:`regressions `, both in manual and automated testing. + +.. _Regressions: + +Regressions +----------- + +Regressions are unintended negative consequences that updates introduce. They appear as +new bugs or failures in previously well-functioning aspect of an Ubuntu release. + +If a package update introduces a regression that makes it through the verification +process to :ref:`updates `, file a bug report about the issue +and add the tag ``regression-update`` to the bug. + +For regressions that only apply to the package in +:ref:`proposed `, follow up on the bug with a detailed +explanation and tag it with ``regression-proposed``. + +Regression tests +~~~~~~~~~~~~~~~~ + +To minimise the risk of :ref:`regressions ` being introduced through +:term:`SRU`, :term:`Canonical` will test each proposed kernel. + +The Ubuntu Platform QA team will perform ``Depth Regression Testing`` on a minimal set of +hardware that represents the different flavours of Ubuntu editions and architectures. This +test verifies that the update didn't introduce hardware-independent +:ref:`regressions `. + +The Ubuntu HW Certification team will perform ``Breadth Hardware Testing`` on release-certified +hardware. This test verifies that the proposed kernel can be successfully installed on the +latest release, that network access is functional, and that no other functionality critical +for Update Manager is missing. + +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 will be made on the bug report. If no testing occurs within +an additional 15 days, totaling 105 days without any testing, the :term:`Stable Release Managers` +will remove the package from :ref:`proposed ` and close the bug +task as ``Won't Fix``. + +Also, updates will be removed from :ref:`proposed ` if +they introduce a nontrivial regression. + +Resources +--------- + +- `StableReleaseUpdates wiki `_ +- `Ubuntu autopkgtest package `_ +- `Ubuntu update-manager package `_ +- `Phasing Ubuntu Stable Release Updates `_ diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 47f7a4cd..fb95d252 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -1123,6 +1123,12 @@ Glossary SRU Abbreviation for :term:`Stable Release Update` + + SRU Verification Team + *Work in Progress* + + Stable Release Managers + *Work in Progress* Stable Release Update *Work in Progress* @@ -1265,6 +1271,11 @@ Glossary See: `discourse.ubuntu.com `_ + Ubuntu ESM Team + *Work in Progress* + + See also: `Ubuntu ESM Team `_ + Ubuntu flavours *Ubuntu flavours* are :term:`Distributions ` of the default :term:`Ubuntu` releases, which choose their own default applications and settings. *Ubuntu flavours* are @@ -1300,6 +1311,15 @@ Glossary Ubuntu Server *Work in Progress* + Ubuntu SRU Team + *Work in Progress* + + See also: `Ubuntu SRU Team _ + + Ubuntu Stable Release + The Ubuntu stable release is the officially published version of Ubuntu and + its set of :term:`packages `. + Ubuntu Summit The *Ubuntu Summit* (US) is a continuation of :term:`Ubuntu Developer Summit` since November 2022. The change in name aims to broadening the scope, which diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt index 42ab27bc..c7ba1c79 100644 --- a/docs/reuse/links.txt +++ b/docs/reuse/links.txt @@ -14,3 +14,6 @@ .. _Ubuntu Studio: https://ubuntustudio.org/ .. _Ubuntu Unity: https://ubuntuunity.org/ .. _Xubuntu: https://xubuntu.org/ + +.. _Ask a bug supervisor: https://answers.launchpad.net/launchpad/+question/140509 +.. _contact the Ubuntu SRU Team: https://wiki.ubuntu.com/StableReleaseUpdates#Contacting_the_SRU_team From e1106b78e72cc82ba6bd15e5c9ef22a6fa51105e Mon Sep 17 00:00:00 2001 From: Damilola Oladele <98895460+activus-d@users.noreply.github.com> Date: Tue, 20 Aug 2024 07:54:08 +0100 Subject: [PATCH 3/6] Update stable-release-updates.rst to improve clarity --- docs/explanation/stable-release-updates.rst | 27 ++++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/explanation/stable-release-updates.rst b/docs/explanation/stable-release-updates.rst index 479709f1..df8efde5 100644 --- a/docs/explanation/stable-release-updates.rst +++ b/docs/explanation/stable-release-updates.rst @@ -13,8 +13,8 @@ operations, and any problem they experience with it can be disruptive. When are Stable Release Updates necessary? ------------------------------------------ -:term:`SRU` require great caution because they're automatically recommended to a very -large number of users. So, when you propose an update, there should be a strong rationale +:term:`SRU` 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 `. You can propose an :term:`SRU` in the following cases: @@ -35,8 +35,9 @@ You can propose an :term:`SRU` in the following cases: Low priority and Extended Security Maintenance (ESM) uploads ------------------------------------------------------------ -Low-priority uploads, such as updates that fix bugs that don't affect users at -runtime, can be staged and bundled with a future :term:`SRU` or security update. +You can stage and bundle low-priority uploads with a future :term:`SRU` or +security update. These uploads may include updates that fix bugs that don't +affect users at runtime. For uploads to stable releases in their :term:`ESM` period, please prepare the :term:`SRU` bug, then contact the :term:`Ubuntu ESM Team`. @@ -126,8 +127,8 @@ Initially, the ``Phased-Update-Percentage`` is set to 10%, with a job running ev hours to monitor for :ref:`regressions `. If no issues are detected, the update percentage increments by 10% until it reaches 100%. So an update will become fully phased after 54 hours. If a regression is found, the update is halted and the -``Phased-Update-Percentage`` is set to 0%. This will cause supported package managers -not to install the update. +``Phased-Update-Percentage`` is set to 0%. This will then cause supported package +managers not to install the update. Investigating halted phased updates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -135,7 +136,7 @@ Investigating halted phased updates To investigate why phasing stopped, use the phased updates report. When investigating an increased rate of crashes, focus on the crashes with the highest -number of occurrences. Examine the Occurrences table to determine if these crashes are +number of occurrences. Examine the occurrences table to determine if these crashes are happening more frequently with the updated version of the package. If they are, investigate the cause and address the crash in a follow-up :term:`SRU`. If not, `contact the Ubuntu SRU Team`_ about overriding the crash report. @@ -155,6 +156,8 @@ containing lines of the form ``source package``, ``version``, and ``$THING_TO_IG ``$THING_TO_IGNORE`` can either be an ``errors.ubuntu.com`` problem URL to ignore or ``increased-rate``. +.. _Verification: + Verification ------------ @@ -205,12 +208,12 @@ or the person performing update verification to ensure that the upload doesn't c Regressions ----------- -Regressions are unintended negative consequences that updates introduce. They appear as -new bugs or failures in previously well-functioning aspect of an Ubuntu release. +Regressions are unintended negative consequences that updates introduce. They appear +as new bugs or failures in previously well-functioning aspect of an Ubuntu release. -If a package update introduces a regression that makes it through the verification -process to :ref:`updates `, file a bug report about the issue -and add the tag ``regression-update`` to the bug. +If a package update introduces a regression that makes it through the +:ref:`verification ` process to :ref:`updates `, +file a bug report about the issue and add the tag ``regression-update`` to the bug. For regressions that only apply to the package in :ref:`proposed `, follow up on the bug with a detailed From 568e4f107741bf252262229359952165aecd5d5e Mon Sep 17 00:00:00 2001 From: Damilola Oladele <98895460+activus-d@users.noreply.github.com> Date: Wed, 21 Aug 2024 09:00:14 +0100 Subject: [PATCH 4/6] Update docs/reference/glossary.rst to solve build error Co-authored-by: Dominik Viererbe --- docs/reference/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index fb95d252..c22fafcf 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -1314,7 +1314,7 @@ Glossary Ubuntu SRU Team *Work in Progress* - See also: `Ubuntu SRU Team _ + See also: `Ubuntu SRU Team `_ Ubuntu Stable Release The Ubuntu stable release is the officially published version of Ubuntu and From ffbdad87eeeb3d3d117ccb89d6629814805a05d3 Mon Sep 17 00:00:00 2001 From: activus-d Date: Wed, 21 Aug 2024 12:04:15 +0100 Subject: [PATCH 5/6] fix broken links --- docs/explanation/stable-release-updates.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/explanation/stable-release-updates.rst b/docs/explanation/stable-release-updates.rst index df8efde5..68182c9f 100644 --- a/docs/explanation/stable-release-updates.rst +++ b/docs/explanation/stable-release-updates.rst @@ -46,7 +46,7 @@ General requirements -------------------- The general requirements for :term:`SRU` are designed to ensure the stability and -reliability of `Ubuntu releases `_. +reliability of :ref:`Ubuntu releases `. To prevent future :ref:`regressions ` when users upgrade to newer Ubuntu versions, bugs should be fixed in the current development release before being @@ -74,7 +74,7 @@ The following steps outline the process for submitting and managing an 1. Ensure that the bug is fixed in the current development release and that its status is marked as ``Fix Released``. If the source package has changed names - between `releases `_, add the new source package as ``Also affecting`` + between :ref:`releases `, add the new source package as ``Also affecting`` in the bug report. 2. Don't create a meta-bug with a title like ``Please SRU this`` instead of using existing bug reports. This approach is redundant and lacks transparency for the @@ -104,8 +104,8 @@ The following steps outline the process for submitting and managing an change the bug status to ``In Progress``. The status will be automatically updated to ``Fix Committed`` once accepted into ``release-proposed``. 6. Ensure that the version number doesn't conflict with any future versions in other - Ubuntu releases. Also, include a reference to the :term:`SRU` bug number in the - changelog using the ``LP: #NNNNNN`` format, and only reference public bugs. + :ref:`Ubuntu releases `. Also, include a reference to the :term:`SRU` bug + number in the changelog using the ``LP: #NNNNNN`` format, and only reference public bugs. 7. Once the :term:`Ubuntu SRU Team` reviews and accepts your upload, test the binaries in the :term:`Ubuntu Archive` and follow up in the bug report with your verification results. The :term:`Ubuntu SRU Team` will evaluate the testing feedback and move the @@ -117,7 +117,7 @@ The following steps outline the process for submitting and managing an ``Importance: critical`` label. SRU phasing --------------- +----------- Once a package is released to :ref:`updates `, the update is then phased so that the update is gradually made available to expanding @@ -167,7 +167,7 @@ that which will exist after the package is copied to Generally, this will be with a system that's up to date from :ref:`release `, :ref:`security `, and -:ref:`updates (explanation) `. +:ref:`updates `. It shouldn't include other packages from :ref:`proposed ` or :ref:`backports `, @@ -184,7 +184,7 @@ If you encounter a regression in a package uploaded to 1. File a bug report describing the nature of the regression. #. Tag the bug as ``regression-proposed``. -#. `Ask a bug supervisor`_ to target the bug to the appropriate `Ubuntu releases `_. +#. `Ask a bug supervisor`_ to target the bug to the appropriate :ref:`Ubuntu releases `. #. Follow up on the :term:`SRU` bug report referenced from the package changelog, pointing to the new bug. If there is more than one bug in the :term:`SRU` changelog, follow up to the bug that is most closely related to the regression. @@ -209,7 +209,8 @@ Regressions ----------- Regressions are unintended negative consequences that updates introduce. They appear -as new bugs or failures in previously well-functioning aspect of an Ubuntu release. +as new bugs or failures in previously well-functioning aspect of an +:ref:`Ubuntu release `. If a package update introduces a regression that makes it through the :ref:`verification ` process to :ref:`updates `, From 3d04e43a0269e319fb1dbadb9dccf597de552af2 Mon Sep 17 00:00:00 2001 From: Damilola Oladele <98895460+activus-d@users.noreply.github.com> Date: Fri, 13 Sep 2024 05:06:13 +0100 Subject: [PATCH 6/6] Redundant links removed; update glossary; remove links from reuse/links.txt and add them to explanation/releases.rst Co-authored-by: Dominik Viererbe --- docs/explanation/releases.rst | 2 + docs/explanation/stable-release-updates.rst | 116 +++++++++----------- docs/reference/glossary.rst | 6 + docs/reuse/links.txt | 3 - 4 files changed, 62 insertions(+), 65 deletions(-) diff --git a/docs/explanation/releases.rst b/docs/explanation/releases.rst index e336cc93..ad4cb0ef 100644 --- a/docs/explanation/releases.rst +++ b/docs/explanation/releases.rst @@ -226,3 +226,5 @@ Resources - `Ubuntu wiki -- point release process `_ - `Ubuntu wiki -- end of life process `_ - `Ubuntu releases `_ +- `Ask a bug supervisor ` +- `contact the Ubuntu SRU Team ` diff --git a/docs/explanation/stable-release-updates.rst b/docs/explanation/stable-release-updates.rst index 68182c9f..ce610646 100644 --- a/docs/explanation/stable-release-updates.rst +++ b/docs/explanation/stable-release-updates.rst @@ -1,9 +1,9 @@ Stable Release Updates (SRU) ============================ -After publication of the :term:`Ubuntu Stable Release`, there may be a need +After publication of a :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 :term:`Stable Release Update (SRU) `. +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 of @@ -13,21 +13,21 @@ operations, and any problem they experience with it can be disruptive. When are Stable Release Updates necessary? ------------------------------------------ -:term:`SRU` require great caution because they're automatically recommended to a large +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 `. -You can propose an :term:`SRU` in the following cases: +You can propose an SRU in the following cases: - To fix high-impact bugs, including those that may directly cause security - vulnerabilities, severe :ref:`regressions ` from the previous release, or + 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 `, usually under strict conditions. -- To update commercial software in the :term:`Canonical` partner archive. +- 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. @@ -35,22 +35,22 @@ You can propose an :term:`SRU` in the following cases: Low priority and Extended Security Maintenance (ESM) uploads ------------------------------------------------------------ -You can stage and bundle low-priority uploads with a future :term:`SRU` or +You can stage and bundle low-priority uploads with a future SRU or security update. These uploads may include updates that fix bugs that don't affect users at runtime. For uploads to stable releases in their :term:`ESM` period, please prepare the -:term:`SRU` bug, then contact the :term:`Ubuntu ESM Team`. +SRU bug, then contact the :term:`Ubuntu ESM Team`. General requirements -------------------- -The general requirements for :term:`SRU` are designed to ensure the stability and +The general requirements for SRU are designed to ensure the stability and reliability of :ref:`Ubuntu releases `. -To prevent future :ref:`regressions ` when users upgrade to newer -Ubuntu versions, bugs should be fixed in the current development release before being -considered for an :term:`SRU`. +To prevent future regressions when users upgrade to newer +Ubuntu versions, bugs should be fixed in the :term:`current development release ` before being +considered for an SRU. Also, all subsequent supported releases should be fixed at the same time. This ensures consistency across different Ubuntu versions. There are two exceptions to @@ -70,16 +70,16 @@ SRU procedures -------------- The following steps outline the process for submitting and managing an -:term:`SRU` in Ubuntu: +SRU in Ubuntu: 1. Ensure that the bug is fixed in the current development release and that its status is marked as ``Fix Released``. If the source package has changed names - between :ref:`releases `, add the new source package as ``Also affecting`` + between releases, add the new source package as ``Also affecting`` in the bug report. 2. Don't create a meta-bug with a title like ``Please SRU this`` instead of using existing bug reports. This approach is redundant and lacks transparency for the original bug reporters, whose feedback is important for verification. Such meta-bugs - will be invalidated by the :term:`Ubuntu SRU Team`, and the corresponding uploads + will be invalidated by the Ubuntu SRU Team, and the corresponding uploads will be rejected from the queue. 3. Ensure that the bug report for the issue is public. If the bug has been reported privately and can't be published, create a separate public bug report in @@ -93,38 +93,37 @@ The following steps outline the process for submitting and managing an instructions should be clear enough for someone unfamiliar with the package to verify the fix. - **Where Problems Could Occur**: Highlight potential areas where - :ref:`regressions ` might happen. This section should show that + regressions might happen. This section should show that potential risks have been considered. It should also provide additional test cases - to ensure there are no :ref:`regressions `. + to ensure there are no regressions. -5. Prepare the :term:`SRU` upload, attach a ``debdiff`` to the bug, and request sponsorship +5. Prepare the SRU upload, attach a ``debdiff`` to the bug, and request sponsorship by subscribing ``ubuntu-sponsors`` to the bug. The upload should have the correct release in the changelog header, a detailed and user-readable changelog and no unrelated changes. If you can upload directly, use ``dput`` as normal. Once uploaded, change the bug status to ``In Progress``. The status will be automatically updated to ``Fix Committed`` once accepted into ``release-proposed``. 6. Ensure that the version number doesn't conflict with any future versions in other - :ref:`Ubuntu releases `. Also, include a reference to the :term:`SRU` bug + Ubuntu releases. Also, include a reference to the SRU bug number in the changelog using the ``LP: #NNNNNN`` format, and only reference public bugs. -7. Once the :term:`Ubuntu SRU Team` reviews and accepts your upload, test the binaries +7. Once the Ubuntu SRU Team reviews and accepts your upload, test the binaries in the :term:`Ubuntu Archive` and follow up in the bug report with your verification - results. The :term:`Ubuntu SRU Team` will evaluate the testing feedback and move the + results. The Ubuntu SRU Team will evaluate the testing feedback and move the package into :ref:`updates ` after it passes a minimum aging period of 7 days. -8. Subscribe to the bugmail of the package in :term:`Launchpad`, and monitor - :term:`Launchpad` for bug reports relating to the update for at least one week. If +8. Subscribe to the bugmail of the package in Launchpad, and monitor + Launchpad for bug reports relating to the update for at least one week. If you notice and confirm any regression, document it in a bug report marked with an ``Importance: critical`` label. SRU phasing ----------- -Once a package is released to :ref:`updates `, -the update is then phased so that the update is gradually made available to expanding -subsets of Ubuntu users. +Once a package is released to ``updates``, the update is then phased so that the update +is gradually made available to expanding subsets of Ubuntu users. Initially, the ``Phased-Update-Percentage`` is set to 10%, with a job running every 6 -hours to monitor for :ref:`regressions `. If no issues are detected, the +hours to monitor for regressions. If no issues are detected, the update percentage increments by 10% until it reaches 100%. So an update will become fully phased after 54 hours. If a regression is found, the update is halted and the ``Phased-Update-Percentage`` is set to 0%. This will then cause supported package @@ -138,13 +137,13 @@ To investigate why phasing stopped, use the phased updates report. When investigating an increased rate of crashes, focus on the crashes with the highest number of occurrences. Examine the occurrences table to determine if these crashes are happening more frequently with the updated version of the package. If they are, -investigate the cause and address the crash in a follow-up :term:`SRU`. If not, -`contact the Ubuntu SRU Team`_ about overriding the crash report. +investigate the cause and address the crash in a follow-up SRU. If not, +contact the :term:`Ubuntu SRU Team` about overriding the crash report. For new errors, verify that they're indeed new by reviewing the versions table and checking the ``Traceback`` or ``Stacktrace`` to determine if the error originates from the updated package or an underlying library. If you believe the error wasn't caused by the update, -you can `contact the Ubuntu SRU Team`_ to override the crash. +you can contact the :term:`Ubuntu SRU Team` to override the crash. Overriding halted phased updates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -161,13 +160,11 @@ containing lines of the form ``source package``, ``version``, and ``$THING_TO_IG Verification ------------ -:term:`SRU` verification should be done in a software environment that closely resembles -that which will exist after the package is copied to -:ref:`updates `. +SRU verification should be done in a software environment that closely resembles +that which will exist after the package is copied to ``updates``. Generally, this will be with a system that's up to date from :ref:`release `, -:ref:`security `, and -:ref:`updates `. +:ref:`security `, and ``updates``. It shouldn't include other packages from :ref:`proposed ` or :ref:`backports `, @@ -176,32 +173,30 @@ be updated if they're generally installed. If the fix is sufficient, the :term:`SRU Verification Team` will update the bug status to ``In Progress``, and change the ``verification-needed-$RELEASE`` tag to -``verification-failed-$RELEASE``. If the fix is sufficent, the :term:`SRU Verification Team` +``verification-failed-$RELEASE``. If the fix is sufficent, the SRU Verification Team will tag it as ``verification-done-$RELEASE``. If you encounter a regression in a package uploaded to -:ref:`proposed `, do the following: +proposed, do the following: 1. File a bug report describing the nature of the regression. #. Tag the bug as ``regression-proposed``. -#. `Ask a bug supervisor`_ to target the bug to the appropriate :ref:`Ubuntu releases `. -#. Follow up on the :term:`SRU` bug report referenced from the package changelog, pointing - to the new bug. If there is more than one bug in the :term:`SRU` changelog, follow up to +#. Ask a :term:`Bug supervisor` to target the bug to the appropriate Ubuntu releases. +#. Follow up on the SRU bug report referenced from the package changelog, pointing + to the new bug. If there is more than one bug in the SRU changelog, follow up to the bug that is most closely related to the regression. -#. Set the ``verification-failed-$RELEASE`` tag on the corresponding :term:`SRU` bug report. +#. Set the ``verification-failed-$RELEASE`` tag on the corresponding SRU bug report. .. note:: ``$RELEASE`` represents the release name of your upload. -Packages accepted into :ref:`proposed ` automatically trigger -related :term:`autopkgtests `. +Packages accepted into proposed automatically trigger related ``autopkgtests``. -If an :term:`SRU` upload triggers an :term:`autopkgtests ` regression, -the target package will not be released into :ref:`updates ` until -the issue is resolved. Once the tests are completed, the pending :term:`SRU` page provides -links to any failures noticed for the selected upload. It's the responsibility of the uploader -or the person performing update verification to ensure that the upload doesn't cause any -:ref:`regressions `, both in manual and automated testing. +If an SRU upload triggers an ``autopkgtests`` regression, the target package will +not be released into updates until the issue is resolved. Once the tests are completed, +the pending SRU page provides links to any failures noticed for the selected upload. +It's the responsibility of the uploader or the person performing update verification to +ensure that the upload doesn't cause any regressions, both in manual and automated testing. .. _Regressions: @@ -209,27 +204,24 @@ Regressions ----------- Regressions are unintended negative consequences that updates introduce. They appear -as new bugs or failures in previously well-functioning aspect of an -:ref:`Ubuntu release `. +as new bugs or failures in previously well-functioning aspect of an Ubuntu release. If a package update introduces a regression that makes it through the -:ref:`verification ` process to :ref:`updates `, -file a bug report about the issue and add the tag ``regression-update`` to the bug. +:ref:`verification ` process to ``updates``, file a bug report about +the issue and add the tag ``regression-update`` to the bug. -For regressions that only apply to the package in -:ref:`proposed `, follow up on the bug with a detailed -explanation and tag it with ``regression-proposed``. +For regressions that only apply to the package in proposed, follow up on the bug with +a detailed explanation and tag it with ``regression-proposed``. Regression tests ~~~~~~~~~~~~~~~~ -To minimise the risk of :ref:`regressions ` being introduced through -:term:`SRU`, :term:`Canonical` will test each proposed kernel. +To minimise the risk of regressions being introduced through +SRU, :term:`Canonical` will test each proposed kernel. The Ubuntu Platform QA team will perform ``Depth Regression Testing`` on a minimal set of hardware that represents the different flavours of Ubuntu editions and architectures. This -test verifies that the update didn't introduce hardware-independent -:ref:`regressions `. +test verifies that the update didn't introduce hardware-independent regressions. The Ubuntu HW Certification team will perform ``Breadth Hardware Testing`` on release-certified hardware. This test verifies that the proposed kernel can be successfully installed on the @@ -242,10 +234,10 @@ 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 will be made on the bug report. If no testing occurs within an additional 15 days, totaling 105 days without any testing, the :term:`Stable Release Managers` -will remove the package from :ref:`proposed ` and close the bug +will remove the package from proposed and close the bug task as ``Won't Fix``. -Also, updates will be removed from :ref:`proposed ` if +Also, updates will be removed from proposed if they introduce a nontrivial regression. Resources diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index c22fafcf..c543f561 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -206,6 +206,9 @@ Glossary See also: `Software bug (Wikipedia) `_ + Bug supervisor + *Work in Progress* + Bug Tracking System A platform used by software development teams to manage and monitor the progress of reported issues or :term:`Bugs ` within a software project. It provides @@ -239,6 +242,9 @@ Glossary See: `discourse.canonical.com `_ + Canonical partner archive + *Work in Progress* + CD Abbreviation for :term:`Continuous Delivery` diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt index c7ba1c79..42ab27bc 100644 --- a/docs/reuse/links.txt +++ b/docs/reuse/links.txt @@ -14,6 +14,3 @@ .. _Ubuntu Studio: https://ubuntustudio.org/ .. _Ubuntu Unity: https://ubuntuunity.org/ .. _Xubuntu: https://xubuntu.org/ - -.. _Ask a bug supervisor: https://answers.launchpad.net/launchpad/+question/140509 -.. _contact the Ubuntu SRU Team: https://wiki.ubuntu.com/StableReleaseUpdates#Contacting_the_SRU_team