docs/backports.md

   1 Backports policy
   2 ===
   3
   4 Aims
   5 ---
   6
   7  * Known bugs should be fixed in stable versions of GLib
   8  * New bugs must not be introduced into stable versions of GLib
   9  * Users and distributors should be able to rely on micro stable releases
  10    working as drop-in replacements for the previous releases on that stable
  11    branch, requiring no packaging changes, or recompilation or build system
  12    changes in dependent projects
  13  * Effort is only spent on [supported versions](../SECURITY.md#user-content-supported-versions)
  14
  15 Policy
  16 ---
  17
  18  * Bug fixes and documentation fixes should be backported to the current stable
  19    branch of GLib, from the current unstable branch
  20  * Backports should only be done to
  21    [supported versions](../SECURITY.md#user-content-supported-versions) of GLib
  22  * New features must not be backported
  23  * Any change which will require packaging changes in a distribution should not
  24    be backported unless unavoidable to fix a widely-occurring bug
  25  * If a backported change does affect packaging or use of GLib, it must be
  26    listed prominently in the release notes for that stable release
  27  * Any change which requires changes or additions to translatable strings should
  28    not be backported unless unavoidable to fix a widely-occurring bug
  29    - If possible, existing translatable strings should be reused
  30    - If unavoidable, liaise with the GNOME Translation Team and ensure string
  31      changes are landed with plenty of time to allow translators to provide new
  32      translations
  33    - See https://wiki.gnome.org/TranslationProject/HandlingStringFreezes
  34  * API or ABI changes (including API additions) must not be backported
  35    - A commit which changes the documented behaviour of a function counts as an
  36      API break
  37  * It is discretionary whether fixes to test cases, or new test cases, are
  38    backported, based on a maintainer’s assessment of the effort required to
  39    backport vs the value in running those tests on a stable branch
  40    - The risk of backporting changes to tests is that they fail or become flaky,
  41      and require further work on the stable branch to fix them
  42  * All backports must be submitted as a merge request against the stable branch,
  43    must pass through continuous integration, and must be reviewed by a
  44    maintainer (other than the person submitting the merge request)
  45    - The reviewer should first assess whether the backport is necessary, and
  46      then review it as with any other merge request
  47    - The submitter must set a stable release milestone on the merge request, so
  48      that the next stable release can’t be accidentally made before it’s merged
  49  * Typically, backports are trivial cherry-picks of commits from the unstable
  50    branch — changes to the unstable branch which are intended to be backported
  51    should be structured so that backporting is easier
  52    - For example, by splitting changes to be backported into a separate commit
  53      from those which should not be backported, or splitting out changes which
  54      are more likely to cause conflicts when cherry-picked
  55  * Backports should be done as soon as a fix lands on the unstable branch,
  56    rather than waiting until when the next stable release is due and then
  57    backporting multiple changes from the unstable branch at once. This gives
  58    more opportunity for backported changes to be tested, and reduces the chance
  59    of backporting the wrong thing, or missing a backport.
  60  * These rules are not entirely prescriptive: there may be situations where
  61    maintainers agree that a backport is necessary even if it breaks some of
  62    these rules, due to the balance of fixing a critical bug vs keeping things
  63    easy for distribution maintainers