Backports policy
===

Aims
---

 * Known bugs should be fixed in stable versions of GLib
 * New bugs must not be introduced into stable versions of GLib
 * Users and distributors should be able to rely on micro stable releases
   working as drop-in replacements for the previous releases on that stable
   branch, requiring no packaging changes, or recompilation or build system
   changes in dependent projects
 * Effort is only spent on [supported versions](../SECURITY.md#user-content-supported-versions)

Policy
---

 * Bug fixes and documentation fixes should be backported to the current stable
   branch of GLib, from the current unstable branch
 * Backports should only be done to
   [supported versions](../SECURITY.md#user-content-supported-versions) of GLib
 * New features must not be backported
 * Any change which will require packaging changes in a distribution should not
   be backported unless unavoidable to fix a widely-occurring bug
 * If a backported change does affect packaging or use of GLib, it must be
   listed prominently in the release notes for that stable release
 * Any change which requires changes or additions to translatable strings should
   not be backported unless unavoidable to fix a widely-occurring bug
   - If possible, existing translatable strings should be reused
   - If unavoidable, liase with the GNOME Translation Team and ensure string
     changes are landed with plenty of time to allow translators to provide new
     translations
   - See https://wiki.gnome.org/TranslationProject/HandlingStringFreezes
 * API or ABI changes (including API additions) must not be backported
   - A commit which changes the documented behaviour of a function counts as an
     API break
 * It is discretionary whether fixes to test cases, or new test cases, are
   backported, based on a maintainer’s assessment of the effort required to
   backport vs the value in running those tests on a stable branch
   - The risk of backporting changes to tests is that they fail or become flaky,
     and require further work on the stable branch to fix them
 * All backports must be submitted as a merge request against the stable branch,
   must pass through continuous integration, and must be reviewed by a
   maintainer (other than the person submitting the merge request)
   - The reviewer should first assess whether the backport is necessary, and
     then review it as with any other merge request
   - The submitter must set a stable release milestone on the merge request, so
     that the next stable release can’t be accidentally made before it’s merged
 * Typically, backports are trivial cherry-picks of commits from the unstable
   branch — changes to the unstable branch which are intended to be backported
   should be structured so that backporting is easier
   - For example, by splitting changes to be backported into a separate commit
     from those which should not be backported, or splitting out changes which
     are more likely to cause conflicts when cherry-picked
 * These rules are not entirely prescriptive: there may be situations where
   maintainers agree that a backport is necessary even if it breaks some of
   these rules, due to the balance of fixing a critical bug vs keeping things
   easy for distribution maintainers