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

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 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