diff --git a/docs/backports.md b/docs/backports.md new file mode 100644 index 000000000..b8157b8cc --- /dev/null +++ b/docs/backports.md @@ -0,0 +1,58 @@ +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