fesco / fesco-docs

Clone
Source Code
GIT

#38 Updates policy: Clean up asciidoc conversion, freshen content
Merged 3 years ago by zbyszek. Opened 3 years ago by ferdnyc.
fesco/ ferdnyc/fesco-docs adoc-conversion-2  into  master

file modified
+178 -128 
@@ -3,7 +3,8 @@ 
 

  Fedora has differing policies for each of its branches. This document describes for maintainers what
 

  sort of updates should be created in packages for each of the various branches of existing Fedora.
 

  In the event of questions or clarifications, please file a
 

- link:https://fedorahosted.org/fesco/newticket[FESCo trac ticket] or discuss on the devel list. In
 

+ link:https://pagure.io/fesco/new_issue[FESCo ticket] or discuss on the
 

+ link:https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel list]. In
 

  general, releases should go from less conservative (rawhide) to more so (the oldest supported stable
 

  release). This document attempts to describe when and what kinds of updates maintainers should push
 

  to Fedora users of its various branches. The
 
@@ -11,8 +12,8 @@ 
 

  Fedora Board includes more high level discussion and philosophy, while this
 

  document is more a practical guide. Refer to
 

  link:https://fedoraproject.org/wiki/Package_update_HOWTO[Package update HOWTO] for the technical steps on
 

- pushing the updates. The link:https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle[Fedora Release
 

- Life Cycle] provides a more detailed overview of the development process.
 

+ pushing the updates. The link:https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle[Fedora Release Life Cycle]
 

+ provides a more detailed overview of the development process.
 

  

  == Rawhide / devel / master
 

  
@@ -20,7 +21,7 @@ 
 

  updates built for rawhide are composed every day and pushed out to all rawhide consumers.  New builds against
 

  this tree also are added to the build root (ie, other packages build from them).
 

  

- repos available: link:https://fedoraproject.org/wiki/Repositories#rawhide[_rawhide_]
 

+ Repos available: link:https://fedoraproject.org/wiki/Repositories#rawhide[_rawhide_]
 

  

  Since link:https://fedoraproject.org/wiki/Changes/GatingRawhidePackages[Rawhide Gating change] was introduced,
 

  package updates in Fedora Rawhide need to pass verification before they land in the rawhide repositories. This
 
@@ -35,20 +36,22 @@ 
 

  

  For updates to rawhide packages, Maintainers SHOULD:
 

  

- * Try not to push a clearly broken build (breaks the default buildroot package set, etc)
 

- * When a proposed update contains an ABI or API change: notify *a week in advance* both fedora-devel
 

-   and maintainers directly (using the` _packagename-owner@_` alias) whose packages depend on yours to
 

-   rebuild or offer to do these rebuilds for them.
 

+ * Try not to push a broken build (breaks the default buildroot package set, etc.).
 

+ * When a proposed update contains an ABI or API change: notify *a week in advance* both the
 

+   link:https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel list]
 

+   and maintainers directly (using the ``_packagename_-\owner@fedoraproject.org`` alias)
 

+   whose packages depend on yours to rebuild or offer to do these rebuilds for them.
 

  * Use a separate buildsystem tag when dealing with mass builds of many packages, so they can land at
 

-   the same time. File a ticket with link:https://fedorahosted.org/rel-eng/newticket[rel-eng] for this.
 

+   the same time. File a link:https://pagure.io/releng/new_issue[rel-eng ticket] for this.
 

  * Feel free to push out the newest version of packages as long as they do not cause breakage. Also
 

    keep in mind when the next Fedora release will be branched off, and be fairly confident that there
 

    will be a stable enough release in time for the next Fedora release. Otherwise you may have to
 

    back down to an older, stable version after the branching, which may involve epochs and other
 

    inconveniences.
 

- * If approved by FESCo push pre-release versions of low level packages. Certain low-level packages
 

-   (approved by FESCo), including (but not limited to) glibc and gcc to provide pre-release versions
 

-   here. The benefits of the early real-world testing of and upstream collaboration on these key
 

+ * If approved by FESCo, push pre-release versions of low level packages.
 

+   FESCo approves certain packages, including (but not limited to) ``glibc`` and ``gcc``,
 

+   to provide pre-release versions here.
 

+   The benefits of the early real-world testing of and upstream collaboration on these key
 

    packages far exceeds the risks that they may introduce.
 

  

  == Branched release
 
@@ -64,16 +67,16 @@ 
 

  === https://fedoraproject.org/wiki/Releases/Branched[Branched], pre-Bodhi enabling
 

  

  For a short time after link:https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle[the branch event
 

- happens] but before the <<bodhi-enabling>> point, the Branched release works just like Rawhide:
 

+ happens] but before the <<bodhi-enabling>> point, the Branched release works exactly like Rawhide:
 

  builds submitted by packagers are considered
 

  link:https://fedoraproject.org/wiki/Repositories#stable[stable] immediately, and sent to the
 

  link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_ repository] directly in the next nightly
 

- compose. There are no restrictions beyond those for Rawhide at this point, but maintainers SHOULD be
 

- thinking about stabilization from this point onwards, and making sure their packages will be in good
 

+ compose. There are no restrictions beyond those for Rawhide at this point, but maintainers *SHOULD* be
 

+ thinking about stabilization from this point onward, and making sure their packages will be in good
 

  condition well in advance of the stable release. Some packages will be signed at this point, but not
 

  all of them. You may have to use `--nogpgcheck` to install or update.
 

  

- repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_]
 

+ Repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_]
 

  

  [[bodhi-enabling]]
 

  === Bodhi enabling
 
@@ -82,12 +85,13 @@ 
 

  this point *for the entire remaining lifetime of the release*, all updates must go through Bodhi
 

  before they can be marked _stable_ and moved to either
 

  link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_] or
 

- link:https://fedoraproject.org/wiki/Repositories#updates[_updates_]. At present, the _Bodhi enabling
 

- point_ occurs on the day of the link:https://fedoraproject.org/wiki/Milestone_freezes[Beta freeze], but
 

- it is important to remember that they are distinct events: the Beta freeze lasts until Beta release,
 

- but Bodhi enabling is permanent.
 

+ link:https://fedoraproject.org/wiki/Repositories#updates[_updates_].
 

+ At present, the _Bodhi enabling point_ occurs on the day of the
 

+ link:https://fedoraproject.org/wiki/Milestone_freezes[Beta freeze],
 

+ but it is important to remember that they are distinct events:
 

+ the Beta freeze lasts until Beta release, but Bodhi enabling is permanent.
 

  

- repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_],
 

+ Repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_],
 

  link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

  

  At this point all packages will be signed and gpgcheck should be enabled for all installs/updates.
 
@@ -95,25 +99,30 @@ 
 

  [[pre-beta]]
 

  === Pre Beta
 

  

- This is the time between the _Bodhi enabling point_ and the Beta release. During this time we are
 

+ This is the time between the <<bodhi-enabling>> point and the Beta release. During this time we are
 

  attempting to stabilize the major versions of software that will be shipped with the final release
 

  of the OS. Major updates can be tolerated, but breaking things for early testers should be avoided
 

  if possible. Additionally, as we get close to Alpha or Beta releases any change that breaks composes
 

  of Live media, install media or testing should be avoided. Packages for Changes should be landing
 

  and getting major testing.
 

  

- repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_], link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

+ Repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_],
 

+ link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

  

- From this point onwards Maintainers **MUST**footnote:[_Must_ requirements are enforced by Bodhi.]:
 

+ From this point onward Maintainers
 

+ **MUST**footnote:enforced[_Must_ requirements are enforced by Bodhi.]:
 

  

  * Push all updates first to updates-testing.
 

- * All link:https://fedoraproject.org/wiki/Critical_path_package[critical path] updates MUST either get
 

-   one +1 karma, OR spend at least 14 days in updates-testing and have no negative karma before being
 

-   moved to stable.
 

- * All non critical path updates MUST either reach the prescribed karma level for that update, OR
 

-   spend at least 3 days in updates-testing before being allowed to move to stable.
 

+ * All link:https://fedoraproject.org/wiki/Critical_path_package[critical path] updates
 

+   *MUST* either get one +1 karma,
 

+   *OR* spend at least 14 days in updates-testing and have no negative karma
 

+   before being moved to stable.
 

+ * All non critical path updates
 

+   *MUST* either reach the prescribed karma level for that update,
 

+   *OR* spend at least 3 days in updates-testing
 

+   before being allowed to move to stable.
 

  

- and Maintainers SHOULD (not enforced):
 

+ and Maintainers *SHOULD* (not enforced):
 

  

  * Avoid ABI/API changes where possible. If unavoidable, should coordinate a side-tag to rebuild
 

    packages in or a mass build/update, by filing a https://pagure.io/releng/new_issue[releng ticket].
 
@@ -121,66 +130,82 @@ 
 

  [[milestone-freezes]]
 

  ==== Milestone freezes
 

  

- During this period there are two link:https://fedoraproject.org/wiki/Milestone_freezes[Milestone
 

- freezes], _Alpha freeze_ and _Beta freeze_. Each is scheduled to run for the two weeks leading up to
 

+ During this period there are two link:https://fedoraproject.org/wiki/Milestone_freezes[Milestone freezes],
 

+ _Alpha freeze_ and _Beta freeze_. Each is scheduled to run for the two weeks leading up to
 

  the release date (and in fact lasts until the release is signed off, even if it is delayed). During
 

  these times, builds will not be marked _stable_ and moved from
 

  link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_] to
 

- link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_] (and hence included in the milestone
 

- release composes) except for those approved under the
 

- link:https://fedoraproject.org/wiki/QA:SOP_blocker_bug_process[QA SOP blocker bug process] or
 

- link:https://fedoraproject.org/wiki/QA:SOP_freeze_exception_bug_process[QA SOP freeze exception bug process].
 

+ link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_]
 

+ (and hence included in the milestone release composes) except for those approved under the Fedora QA team
 

+ link:https://fedoraproject.org/wiki/QA:SOP_blocker_bug_process[blocker bug process] or
 

+ link:https://fedoraproject.org/wiki/QA:SOP_freeze_exception_bug_process[freeze exception bug process].
 

  Once the milestone release is made, these freezes are lifted.
 

- These freezes are technically not a part of the Updates Policy, but are briefly mentioned here for
 

- clarity. The link:https://fedoraproject.org/wiki/Milestone_freezes[Milestone freezes] page provides more
 

- details and is the canonical reference in case of any conflict.
 

+ These freezes are technically not a part of the Updates Policy,
 

+ but are briefly mentioned here for clarity.
 

+ The link:https://fedoraproject.org/wiki/Milestone_freezes[Milestone freezes]
 

+ page provides more details and is the canonical reference in case of any conflict.
 

  

  [[beta-to-pre-release]]
 

  === Beta to Pre Release
 

  

  This is the time between the Beta release and the
 

- link:https://fedoraproject.org/wiki/Milestone_freezes[Final freeze]. The branched tree should now be
 

- stabilized and prepared for release. Major changes should be avoided during this period. Bear in
 

- mind that in most cases, the state your package has reached in the stable
 

- link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_] repository at the time of the Final
 

- freeze is the state it will be in for the final release.
 

- 

- repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_], link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

+ link:https://fedoraproject.org/wiki/Milestone_freezes[Final freeze].
 

+ The branched tree should now be stabilized and prepared for release.
 

+ Major changes should be avoided during this period.
 

+ Bear in mind that in most cases, the state your package has reached in the stable
 

+ link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_]
 

+ repository at the time of the Final freeze is the state it will be in for the final release.
 

+ 

+ Repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_],
 

+ link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

  

- From this point onwards maintainers **MUST**[multiblock footnote omitted]:
 

+ From this point onward maintainers **MUST**footnote:enforced[]:
 

  

  * Avoid Major version updates, ABI breakage or API changes if at all possible.
 

  * Push updates first to updates-testing.
 

- * All link:https://fedoraproject.org/wiki/Critical_path_package[critical path] updates MUST either have
 

-   a sum of +2 karma, OR spend at least 14 days in updates-testing and have no negative karma.
 

- * All non critical path updates MUST either reach the prescribed karma level for that update, OR
 

-   spend at least 7 days in updates-testing before being allowed to go to stable.
 

+ * All link:https://fedoraproject.org/wiki/Critical_path_package[critical path]
 

+   updates
 

+   *MUST* either have a sum of +2 karma,
 

+   *OR* spend at least 14 days in updates-testing
 

+   and have no negative karma.
 

+ * All non critical path updates
 

+   *MUST* either reach the prescribed karma level for that update,
 

+   *OR* spend at least 7 days in updates-testing
 

+   before being allowed to go to stable.
 

  

  [[pre-release]]
 

  === Pre release
 

  

- This is the time after the link:https://fedoraproject.org/wiki/Milestone_freezes[Final freeze]. During
 

- this time the release is being composed and only packages granted exceptions through the
 

- QA:SOP_blocker_bug_process or QA:SOP_freeze_exception_bug_process are marked as _stable_ and moved
 

- to the link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_ repository]. The
 

- link:https://fedoraproject.org/wiki/Repositories#updates[_updates_] repository is enabled at some point
 

- during this time, and packages other than freeze exception / blocker fixes are queued for so called
 

- "zero day" updates, meaning they will be available in the _updates_ repository at the time of the
 

- release (day zero).
 

- 

- repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_], link:https://fedoraproject.org/wiki/Repositories#updates[_updates_], link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

+ This is the time after the link:https://fedoraproject.org/wiki/Milestone_freezes[Final freeze].
 

+ During this time the release is being composed and only packages granted exceptions through the
 

+ link:https://fedoraproject.org/wiki/QA:SOP_blocker_bug_process[blocker bug process] or
 

+ link:https://fedoraproject.org/wiki/QA:SOP_freeze_exception_bug_process[freeze exception bug process]
 

+ are marked as _stable_ and moved to the
 

+ link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_ repository].
 

+ The link:https://fedoraproject.org/wiki/Repositories#updates[_updates_]
 

+ repository is enabled at some point during this time,
 

+ and packages other than freeze exception / blocker fixes are queued for so called "zero day" updates,
 

+ meaning they will be available in the _updates_ repository at the time of the release (day zero).
 

+ 

+ Repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_],
 

+ link:https://fedoraproject.org/wiki/Repositories#updates[_updates_],
 

+ link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

  

  During this period:
 

  

- * All updates pulled into the release **MUST**[multiblock footnote omitted] fix an accepted blocker
 

-   or freeze exception bug.
 

+ * All updates pulled into the release
 

+   **MUST**footnote:enforced[] fix an accepted blocker or freeze exception bug.
 

  * All update pushes will go to updates-testing.
 

- * All link:https://fedoraproject.org/wiki/Critical_path_package[ critical path] updates *MUST* either
 

-   have a sum of +2 karma, *OR* spend at least 14 days in updates-testing and have no negative karma.
 

- * All non critical path updates *MUST* either reach the prescribed karma level for that update, *OR*
 

-   spend at least 7 days in updates-testing before being allowed in stable.
 

+ * All link:https://fedoraproject.org/wiki/Critical_path_package[critical path] updates
 

+   *MUST* either have a sum of +2 karma,
 

+   *OR* spend at least 14 days in updates-testing and have no negative karma.
 

+ * All non critical path updates
 

+   *MUST* either reach the prescribed karma level for that update,
 

+   *OR* spend at least 7 days in updates-testing
 

+   before being allowed in stable.
 

  * Once the _updates_ repository is available, builds marked as
 

-   link:https://fedoraproject.org/wiki/Repositories#stable[_stable_] will go there instead of to
 

+   link:https://fedoraproject.org/wiki/Repositories#stable[_stable_]
 

+   will go there instead of to
 

    link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_].
 

  

  [[stable-releases]]
 
@@ -204,34 +229,48 @@ 
 

  (or provided) a new Python ABI, for example, would almost certainly not be allowed. ABI changes in
 

  general are very strongly discouraged, they force larger update sets on users and they make life
 

  difficult for third-party packagers. Additionally, updates that convert resources or configuration
 

- one way (ie, from older->newer) should be approached with extreme caution as there would be much
 

+ one way (i.e., from older->newer) should be approached with extreme caution as there would be much
 

  less chance of backing out an update that did these things.
 

  

  Whenever possible packagers should work with upstream to come up with stable branch releases or
 

  common patches for older releases, particularly when rebasing would require large dependency chain
 

  updates.
 

  

- repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_], https://fedoraproject.org/wiki/Repositories#updates[_updates_], link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

+ Repos available: link:https://fedoraproject.org/wiki/Repositories#fedora[_fedora_],
 

+ https://fedoraproject.org/wiki/Repositories#updates[_updates_],
 

+ link:https://fedoraproject.org/wiki/Repositories#updates-testing[_updates-testing_]
 

  

  [[updates-to-critical-path-packages]]
 

  === Updates to 'critical path' packages
 

  

- Updates that constitute a part of the 'critical path' package set (defined
 

- below) *including security updates* MUST follow the rules as defined for
 

- link:https://fedoraproject.org/wiki/Critical_path_package[critical path packages] for
 

- pending releases, meaning:
 

+ Updates that constitute a part of the 'critical path' package set
 

+ (defined below) *including security updates*
 

+ *MUST* follow the rules as defined for
 

+ link:https://fedoraproject.org/wiki/Critical_path_package[critical path packages]
 

+ for pending releases, meaning:
 

  

  * At the time of the request to stable, the update needs to have either a
 

-   link:https://fedoraproject.org/wiki/Bodhi[Bodhi karma] sum of 2 *OR*
 

- * It must spend at least 14 days in updates-testing *AND* have no negative
 

+   link:https://fedoraproject.org/wiki/Bodhi[Bodhi karma]
 

+   sum of 2 *OR*
 

+ * It must spend at least 14 days in updates-testing
 

+   *AND* have no negative
 

    link:https://fedoraproject.org/wiki/Bodhi[Bodhi karma] points.
 

  

  For the purposes of this policy, the 'critical path' package set is defined as the following:
 

  

- * The current link:https://fedoraproject.org/wiki/Critical_Path_Packages[critical path package set]
 

+ * The current
 

+   link:https://fedoraproject.org/wiki/Critical_Path_Packages[critical path package set]
 

  * All major desktop environments' core functionality (GNOME, KDE, Xfce, LXDE)
 

- * Package updating frameworks (, )
 

- * Major desktop productivity apps. An initial list would be , (konqueror), , , (kmail).
 

+ * Package updating frameworks
 

+   (link:https://src.fedoraproject.org/rpms/gnome-packagekit[``gnome-packagekit``],
 

+   link:https://src.fedoraproject.org/rpms/apper[``apper``])
 

+ * Major desktop productivity apps.
 

+   An initial list would be
 

+   link:https://src.fedoraproject.org/rpms/firefox[``firefox``],
 

+   link:https://src.fedoraproject.org/rpms/kde-baseapps[``kde-baseapps``](konqueror),
 

+   link:https://src.fedoraproject.org/rpms/thunderbird[``thunderbird``],
 

+   link:https://src.fedoraproject.org/rpms/evolution[``evolution``],
 

+   link:https://src.fedoraproject.org/rpms/kdepim[``kdepim``](kmail).
 

  

  Changes to this definition may only be made by xref:index.adoc[FESCo] or their delegate.
 

  
@@ -243,18 +282,18 @@ 
 

  * reach the criteria laid out in the previous section *OR*
 

  * reach the positive Bodhi karma threshold specified by the updates submitter *OR*
 

  * spend some minimum amount of time in
 

-   link:https://fedoraproject.org/wiki/QA:Updates_Testing[updates-testing], currently one week
 

+   link:https://fedoraproject.org/wiki/QA:Updates_Testing[_updates-testing_], currently one week
 

  

  Package maintainers *MUST*:
 

  

- * Avoid Major version updates, ABI breakage or API changes if at all possible.
 

+ * Avoid Major version updates, ABI breakage, or API changes if at all possible.
 

  * Avoid changing the user experience if at all possible.
 

  * Avoid updates that are trivial or don't affect any Fedora users.
 

  

  Package maintainers *SHOULD*:
 

  

- * Push *only* major bug fixes and security fixes to the previous stable releases (i.e., at present,
 

-   and before).
 

+ * Push *only* major bug fixes and security fixes to the previous stable releases
 

+   (i.e. the current Fedora _N_, and the previous Fedora _N-1_).
 

  

  [[exceptions]]
 

  === Exceptions
 
@@ -265,7 +304,7 @@ 
 

  

  Note that you should open this dialog *BEFORE* you build or push updates. In the event that an issue
 

  is raised in the middle of an update already in progress, make sure you turn off autokarma pushes —
 

- this can be done while the update is pending in bodhi.
 

+ this can be done while the update is pending in Bodhi.
 

  

  The following things would be considered in a exception request.
 

  
@@ -274,18 +313,18 @@ 
 

  * The package is a "leaf" node. Nothing depends on it or requires it.
 

  * The update fixes a security issue that would affect a large number of users.
 

  * The update doesn't change ABI/API and nothing needs to be rebuilt against the new version.
 

- * The update fixes serious bugs that many fedora users are encountering.
 

+ * The update fixes serious bugs that many Fedora users are encountering.
 

  

  Things that would make it less likely to grant a request:
 

  

  * The update converts databases or resources one way to a new format.
 

- * The update requires admin intervention for the service to keep working (config file format
 

-   changes, etc)
 

- * The update causes behavior changes (something that was denied is allowed, etc)
 

- * The update changes the UI the end user sees (moves menus or buttons around, changes option names
 

-   on command line)
 

- * The update fixes bugs that no fedora user has reported nor would affect many fedora users (ie,
 

-   fixes for other platforms or configurations).
 

+ * The update requires admin intervention for the service to keep working
 

+   (config file format changes, etc.)
 

+ * The update causes behavior changes (something that was denied is allowed, etc.)
 

+ * The update changes the UI the end user sees
 

+   (moves menus or buttons around, changes option names on command line)
 

+ * The update fixes bugs that no Fedora user has reported nor would affect many Fedora users
 

+   (i.e., fixes for other platforms or configurations).
 

  

  [[exceptions-list]]
 

  ==== Exceptions list
 
@@ -295,8 +334,8 @@ 
 

  [[kernel-package]]
 

  ===== kernel package
 

  

- * Manpower of kernel maintainers prevents us from easily backporting all the bug fixes, security
 

-   fixes and new hardware enablement we would need to maintain older, no longer supported kernels.
 

+ * Time and resource constraints prevent the kernel maintainers from backporting all the bug fixes,
 

+   security fixes and new hardware enablement we would need to maintain older, no longer supported kernels.
 

  

  * Additionally, multiple kernels can be installed/booted, allowing users to boot older kernels in
 

    the event newer ones fail to work, and allowing time for kernel maintainers to fix any critical
 
@@ -312,16 +351,16 @@ 
 

  ===== girara and zathura
 

  

  These packages are allowed to update in stable releases together.
 

- See https://fedorahosted.org/fesco/ticket/1255
 

+ See link:https://pagure.io/fesco/issue/1255[this FESCo ticket].
 

  

  [[security-fixes]]
 

  ==== Security fixes
 

  

- If upstream does not provide security fixes for a particular release, and if backporting the fix
 

- would be impractical, then the package maintainer(s) MUST open a FESCo ticket for approval to rebase
 

- the package to a version that upstream supports.
 

+ If upstream does not provide security fixes for a particular release,
 

+ and if backporting the fix would be impractical, then the package maintainer(s)
 

+ *MUST* open a FESCo ticket for approval to rebase the package to a version that upstream supports.
 

  

- Package maintainers MUST:
 

+ Package maintainers *MUST*:
 

  

  * Avoid Major version updates, AI breakage, or API changes if at all possible
 

  * Avoid changing the user or developer experience if at all possible
 
@@ -355,7 +394,11 @@ 
 

  hardware music players, cell phones, etc. These packages may also be updated to add support for new
 

  devices or formats in compatible ways.
 

  

- Examples of this type of package: , , ,
 

+ Examples of this type of package:
 

+ link:https://src.fedoraproject.org/rpms/libopenraw[``libopenraw``],
 

+ link:https://src.fedoraproject.org/rpms/libimobiledevice[``libimobiledevice``],
 

+ link:https://src.fedoraproject.org/rpms/calibre[``calibre``],
 

+ link:https://src.fedoraproject.org/rpms/pilot-link[``pilot-link``]
 

  

  [[database-packages]]
 

  ==== Database packages
 
@@ -366,7 +409,9 @@ 
 

  changes to require a new version of the rules engine, then the package may be a candidate for
 

  rebasing.
 

  

- Examples of this type of package: ,
 

+ Examples of this type of package:
 

+ link:https://src.fedoraproject.org/rpms/spamassassin[``spamassassin``],
 

+ link:https://src.fedoraproject.org/rpms/clamav[``clamav``]
 

  

  [[examples]]
 

  ==== Examples
 
@@ -388,33 +433,38 @@ 
 

    major user experience change, and would not be allowed.
 

  

  * WebKit requires an update to solve a security problem. This requires updating Midori to a version
 

-   with some minor menu layout changes. This would be a judgement call based on how intrusive the
 

+   with some minor menu layout changes. This would be a judgment call based on how intrusive the
 

    changes are (removing the File menu would be rude, but moving the plugin configuration menu item
 

    would be acceptable).
 

  

- * Firefox releases an update that only contains changes for other platforms. This update could be
 

-   pushed to rawhide (just to keep up with the latest version), but should not be pushed to stable
 

-   releases, as it does no good to our users and wastes resources to build, update, mirror and
 

-   download to our users.
 

  

- * Terminal fails to build from source when tested in a mass rebuild. An updated package should be
 

-   pushed to rawhide. Fixes for stable releases should be tested and even commited, but unless there
 

-   is a problem with the previous existing build in the stable release, no update should be issued.
 

+ * Firefox releases an update that only contains changes for other platforms.
 

+   This update could be pushed to rawhide (to keep up with the latest version),
 

+   but should not be pushed to stable releases, as it does no good to our users
 

+   and wastes resources to build, update, mirror, and download to our users.
 

+ 

+ * Terminal fails to build from source when tested in a mass rebuild.
 

+   An updated package should be pushed to rawhide.
 

+   Fixes for stable releases should be tested and even committed,
 

+   but unless there is a problem with the previous existing build in the stable release,
 

+   no update should be issued.
 

    This update would not change any user facing functions of the package.
 

  

- * KDE upstream releases a new major version, and at the same time stops supporting the older release
 

-   that is in Fedora N and Fedora N-1. This release includes a large number of bugfixes, mixed with
 

-   enhancements and security fixes. An exception for this type of update would need to consider:
 

-   ability to backport major fixes/security issues, type and amount of bugs fixed, ability to not
 

-   update other parts of fedora for this update (ie, avoid qt or other base library ABI changes),
 

-   amount of testing and end user visible changes. An exception like this would be on a case by case
 

-   bases based on all the above.
 

+ * KDE upstream releases a new major version,
 

+   and at the same time stops supporting the older release that is in Fedora N and Fedora N-1.
 

+   This release includes a large number of bugfixes, mixed with enhancements and security fixes.
 

+   An exception for this type of update would need to consider:
 

+   ability to backport major fixes/security issues,
 

+   type and amount of bugs fixed,
 

+   ability to not update other parts of Fedora for this update (i.e., avoid Qt or other base library ABI changes),
 

+   amount of testing and end user visible changes.
 

+   An exception like this would be on a case by case basis, based on all the above.
 

  

  [[problems-or-issues-with-updates]]
 

  == Problems or issues with Updates
 

  

  In an effort to learn from any mistakes made, in the event of a update causing a widespread or
 

- serious problem for Fedora users, please file a FESCo trac ticket. FESCo will discuss and try and
 

+ serious problem for Fedora users, please file a link:https://pagure.io/fesco/new_issue[FESCo ticket]. FESCo will discuss and try and
 

  work to prevent the issue from happening again. A past record of such issues can be found at
 

  link:https://fedoraproject.org/wiki/Updates_Lessons[Updates Lessons].
 

  
@@ -430,8 +480,7 @@ 
 

  three separate updates, because if the update for package A is pushed stable before the updates for
 

  packages B and C, it will cause dependency problems. There is information on how to submit
 

  multi-package updates in the
 

- link:https://fedoraproject.org/wiki/Package_update_HOWTO#Updating_inter-dependent_packages[package update
 

- HOWTO].
 

+ link:https://fedoraproject.org/wiki/Package_update_HOWTO#Updating_inter-dependent_packages[package update HOWTO].
 

  

  [[taskotron]]
 

  == Taskotron
 
@@ -441,17 +490,18 @@ 
 

  repositories) and an upgrade path check (to ensure the update does not break the upgrade path from
 

  release to release, i.e. that the update does not contain a package versioned higher than the newest
 

  version of the same package available in a later Fedora release). Taskotron adds comments to Bodhi
 

- with the results of these test runs. A failure of either test will cause Bodhi#Karma_Automatism for
 

- the update to be disabled (if it was enabled). If you submit an update that fails one of these
 

- tests, please check the result and fix the problem. If you are sure the failure is an error in the
 

+ with the results of these test runs. Failing either test will disable
 

+ link:https://fedoraproject.org/wiki/Bodhi#Karma_Automatism[Bodhi karma automatism] for
 

+ the update (if it was enabled). If you submit an update that fails one of these
 

+ tests, please check the result and fix the problem. If you are sure there is an error in the
 

  test rather than an error in your package, you may still manually push the update or re-enable karma
 

  automatism.
 

  

- Previously, the old AutoQA system ran similar checks to Taskotron. The scope of these automated
 

- checks is expected to expand in future. The
 

- link:https://fedoraproject.org/wiki/QA:Package_Update_Acceptance_Test_Plan[Package Update Acceptance Test Plan] was written as the original
 

- plan for AutoQA update validation, and may still be seen as a framework for future work on
 

- Taskotron.
 

+ Previously, the old AutoQA system ran similar checks to Taskotron.
 

+ The scope of these automated checks is expected to expand in future.
 

+ The link:https://fedoraproject.org/wiki/QA:Package_Update_Acceptance_Test_Plan[Package Update Acceptance Test Plan]
 

+ was written as the original plan for AutoQA update validation,
 

+ and may still be seen as a framework for future work on Taskotron.
 

  

  [[bodhi-use]]
 

  == Bodhi Use
 
@@ -459,7 +509,7 @@ 
 

  Bodhi is meant as the method for getting updates into an existing release or pre-release. It does
 

  provide a testing mechanism to make sure that nothing unforeseen will arise, but the expectation is
 

  that packages submitted are likely ready to ship as an update. As such, any packages submitted to
 

- bodhi must be done with the intent that the package submitted is ready for general consumption. The
 

+ Bodhi must be done with the intent that the package submitted is ready for general consumption. The
 

  users kind enough to test these packages have come to expect this, and doing anything else moves
 

  against their good will, and is likely to drive testers away. Bodhi and updates-testing are not a
 

  place for experimentation or advanced notification of potentially disruptive updates. These should

This PR replaces my previous #24, which I had to close after a git merge gone wrong. It contains the initial commit from that PR (rebased to apply onto the current HEAD state of the document), plus the update commits I made earlier tonight after realizing the PR had become out-of-date. In summary, those changes comprise:

Fix issues introduced by automated conversion to AsciiDoc, and update/correct content:

  • Example packages for various update types restored¹
    (with links to src.fedoraproject, in the absence of a functioning apps.fedoraproject currently)
  • Replace fedorahosted.org URLs and references to trac with Pagure links
  • Link to HyperKitty for "devel list" mentions
  • Some broken/unlinked wikilinks restored
  • Replace [multiblock footnote omitted] insertions with additional references to a labeled footnote
  • Bold remaining "SHOULD" "MUST" etc.
  • Consistently capitalize "Bodhi" and "Fedora"
  • Try to ensure that 'i.e.' always contains periods, 'etc.' always ends with one, and sentences always employ the serial comma in lists to reduce ambiguity.
  • Make spelling, grammar, punctuation fixes
  • Lean more heavily into semantic newlines for requirements lists, moving *MUST*, *OR*, etc. statements to the start of a line except when they fall at the end of a sentence/bullet-point.

1 — (Note: Some examples are still (even more) out of date (pilot-link!?) and could use reviewing and refreshing.)

5 new commits added

  • Semantic newlines, copyedits
  • 'onwards' (not a word) => 'onward'
  • Semantic newlines for MUST/OR/AND statements
  • Update package links, apps URLs => src URLs
  • Updates policy: Clean up asciidoc conversion
3 years ago

'onwards' (not a word) => 'onward'
"onwards" is alternative spelling for "onward". But I agree that the version without "s" reads better.

"judgement" is a valid word too, but "judgment" is fine too.

In the previous iteration, the only thing that was controversial was the change from "repo" to "collection", and that is not done in this PR. I think all the changes in this PR are straightforward cleanups or formatting changes that don't require voting. I'll go ahead and merge this immediately.

Pull-Request has been merged by zbyszek
3 years ago

@ferdnyc thanks!

'onwards' (not a word) => 'onward'
"onwards" is alternative spelling for "onward". But I agree that the version without "s" reads better.

I admit I can't argue with that. As a language without a formal description or regulating body (as opposed to e.g. French, where the French Académie Française and the Canadian Office québécois de la langue française maintain their respective official language standards), English dictionaries are descriptive, not prescriptive — they react to how the language is being used. So it's a catch-22: literally any common spelling or use of a word can be added, at the editors' sole discretion, at which point it becomes valid by the only criterion available.

(If you look up 'literally' using Google search, the definition is accompanied by an "INFORMAL" alternate : "used for emphasis or to express strong feeling while not being literally true." We're doomed.)

"judgement" is a valid word too, but "judgment" is fine too.

It is, I didn't claim that was invalid. :grinning: (TBH I tend to spell it with the 'e', but Atom's spellchecker prefers 'judgment'.

In the previous iteration, the only thing that was controversial was the change from "repo" to "collection", and that is not done in this PR.

@dcantrel had walked that back anyway. Their followup comment:

Yeah, the more I think about it in this context it doesn't really matter because the intended audience would already be familiar with Fedora specific terms.

I'm fine with either 'repos' or 'repositories'.

Some examples are still (even more) out of date (pilot-link!?)

For the record, the reason I called out pilot-link in particular is that it provides:

Summary      : File transfer utilities between Linux and PalmPilots
URL          : http://www.pilot-link.org/
License      : GPLv2 and GPLv2+ and LGPLv2+ and Public Domain
Description  : This suite of tools allows you to upload and download programs
             : and data files between a Linux/UNIX machine and the PalmPilot. It
             : has a few extra utilities that will allow for things like syncing
             : the PalmPilot's calendar app with Ical. Note that you might still
             : need to consult the sources for pilot-link if you would like the
             : Python, Tcl, or Perl bindings.
             : 
             : Install pilot-link if you want to synchronize your Palm with your
             : Red Hat Linux system.

So... yeah. Granted it's listed merely as an example of "a package [that] primarily serves to interoperate with hardware or network protocols", but still it's a really outdated example.

In fact, now that I see that wiiuse (the Nintendo Wiimote library) is a Fedora package, rather than RPM Fusion like I'd thought, maybe I'll swap that in. It'll be just as outdated 5 years from now, but that's hardware for you.

I'll check whether any of the others can be replaced with more current examples, and open a new PR to update them.
Metadata
None
No Tags
Changes Summary 1
+178 -128
file changed
fesco/modules/ROOT/pages/Updates_Policy.adoc
Powered by Pagure 5.13.3
Documentation • File an Issue • About • SSH Hostkey/Fingerprint
© Red Hat, Inc. and others.