| 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, liaise 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 | |
| * Backports should be done as soon as a fix lands on the unstable branch, | |
| rather than waiting until when the next stable release is due and then | |
| backporting multiple changes from the unstable branch at once. This gives | |
| more opportunity for backported changes to be tested, and reduces the chance | |
| of backporting the wrong thing, or missing a backport. | |
| * 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 |