[glib: 1/2] docs: Add a backports policy

[Philip Withnall <pwithnall src gnome org>]

commit 49cfb3720e0e0bdc4bd5435d57515f17e32bebed
Author: Philip Withnall <pwithnall endlessos org>
Date:   Thu May 19 12:49:39 2022 +0100

    docs: Add a backports policy
    
    This tries to encode all the decision making which goes on when working
    out whether to backport a commit from the unstable to stable branch.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 docs/backports.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
---
diff --git a/docs/backports.md b/docs/backports.md
new file mode 100644
index 0000000000..b8157b8cc9
--- /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