docs/issue-and-merge-request-management.md

   1 Issue and merge request management policy
   2 ===
   3
   4 Aims
   5 ---
   6
   7  * Finding duplicates and related issues and merge requests should be easy when
   8    triaging new ones, or when looking back at the history of a particular piece
   9    of code
  10  * GLib co-maintainers and other interested people should be able to subscribe
  11    to notifications for specific parts of GLib without receiving notifications
  12    for all activity on GLib
  13  * Issues and merge requests which are planned to be in a specific release
  14    should not be accidentally left out of that release
  15  * GLib co-maintainers should be able to easily see how much work is left to do
  16    before a release is ready
  17  * Users and developers should have some idea of whether an issue or merge
  18    request is being actively worked on, the timescale for its completion, and
  19    who’s working on it
  20
  21 Issue triage
  22 ---
  23
  24  * Issues should be triaged shortly after they are filed. Triage should:
  25    - Add labels to categorise the issue, even if it’s about to be closed (this
  26      helps with finding related closed issues in future)
  27    - Close them immediately if they are a duplicate of an existing issue
  28      (`/duplicate #issue`)
  29    - Or if they are out of scope, such as a user support question (which should
  30      be on https://discourse.gnome.org)
  31    - Ask the user for necessary debug information if the issue is valid, a bug,
  32      and not enough information has been provided — extracting debug information
  33      from users is often time-critical because they can only reproduce an issue
  34      under certain conditions, or they lose interest and move on
  35    - Assign the issue to an upcoming milestone if it seems urgent
  36  * Note that triaging an issue does *not* commit the triager to working on the
  37    issue
  38  * If an issue is likely to affect a stable release (as well as the unstable
  39    `main` branch), assign it to the next micro release milestone for that stable
  40    release — the merge request for the fix will be assigned to the next `main`
  41    micro release, and its backport to the next stable micro release
  42
  43 Merge request triage
  44 ---
  45
  46  * Merge requests should be triaged shortly after they are filed. Triage should
  47    proceed as for issues, including labels and milestones
  48  * The milestone for a merge request is the release it is intended to be
  49    included in, and it should match the target branch of the merge request
  50    - It’s important to add milestones to merge requests, as they then show up on
  51      the milestone page and highlight that the release is not yet ready until
  52      they’re all merged
  53    - This prevents releases accidentally being made without containing all the
  54      fixes they’re supposed to
  55  * The ‘assignee’ of the merge request is the person who is working on it,
  56    responding to review feedback
  57  * The ‘reviewer’ of the merge request is the GLib co-maintainer who is actively
  58    reviewing it
  59  * Don’t assign someone else as the reviewer or assignee of a merge request
  60    unless they have said they are willing to do it, otherwise it gives a false
  61    impression that their time is allocated for doing the work
  62    - You may assign someone else as a reviewer or assignee when closing or
  63      merging a merge request, though, if that helps document who has done the
  64      work so they can be appropriately attributed
  65
  66 Labelling issues and merge requests
  67 ---
  68
  69 GLib has a huge number of labels available, one per component of the library
  70 plus several orthogonal labels. The use of labels allows for:
  71  * Easy searching for related issues and duplicates, by filtering on label
  72  * Co-maintainers of GLib to subscribe to issue and merge request notifications
  73    for a set of labels limited to their interests, meaning they don’t have to
  74    subscribe to the full fire hydrant of GLib notifications just to maintain one
  75    or two components
  76  * High-level prioritization of work, such as prioritizing crashes over new
  77    features
  78  * Tracking issues and merge requests through the release lifecycle, so that
  79    (for example) API additions can be done before the API freeze, and merge
  80    requests approved during a code freeze can all be landed when the freeze ends
  81
  82 To subscribe to a specific label, go to
  83 [the labels page](https://gitlab.gnome.org/GNOME/glib/-/labels) and use the
  84 subscription selector next to the labels you’re interested in.
  85
  86 Several labels are worth highlighting:
  87  * Security: Time-critical security issues, which should typically be marked
  88    as confidential.
  89  * Merge After Freeze: Merge requests which have been accepted, but which can’t
  90    be merged yet as GLib is in
  91    [code freeze](https://wiki.gnome.org/ReleasePlanning/Freezes). All MRs tagged
  92    like this will be merged en-masse when the freeze ends.
  93  * Needs Information: Issues which are blocked due to needing more information
  94    from the reporter. These can be closed after 4 weeks if the reporter does not
  95    respond.
  96  * Not GNOME / Out of Scope: Issues which were closed due to not being within
  97    the scope of GLib.
  98  * Newcomers: Issues which are suitable for being taken on by newcomers to GLib.
  99    When labelling an issue as such, please make sure that the issue title is
 100    clear, and the description (or a comment) clearly explains what needs to be
 101    done to fix the issue, to give newcomers the best chance of successfully
 102    submitting a fix.
 103  * Translation / I18N: Issues which relate to translatable strings or other
 104    internationalization or localization problems. Adding this label may cause
 105    the translation team to be looped into an issue or merge request.
 106  * API deprecation: Issues or merge requests which deprecate GLib API, and hence
 107    can only land in an unstable release outside an
 108    [API freeze](https://wiki.gnome.org/ReleasePlanning/Freezes).
 109  * New API: Issues or merge requests which add new GLib API, and hence can only
 110    land in an unstable release outside an
 111    [API freeze](https://wiki.gnome.org/ReleasePlanning/Freezes).
 112  * Intermittent: Issues (such as test failures) which can only be reproduced
 113    intermittently.
 114  * Test failure: Issues which revolve around a unit test failing. Typically
 115    these are opened after a CI run has failed, and are useful for tracking how
 116    often a particular failure happens.
 117  * Test missing: Merge requests which need a unit test to be written before they
 118    can be merged.
 119
 120 Merge request review
 121 ---
 122
 123  * Assign yourself as the ‘reviewer’ of a merge request when you start review;
 124    this helps with tracking notifications, and lets the assignee of the merge
 125    request know whether you are providing a comprehensive review or just some
 126    drive-by comments
 127  * Review the merge request at a high level first: is the change needed, does
 128    it make sense, is it structured correctly; then look at the detail of memory
 129    management, typos, etc.
 130   - If a merge request is large or contains multiple unrelated changes, it is
 131     best to ask the author to split it into multiple parallel merge requests.
 132     This prevents review comments on one part of the merge request from blocking
 133     merging the rest, and allows the reviewer’s time to be split into smaller
 134     and more manageable chunks.
 135  * Submit all your comments as a single review (rather than adding multiple
 136    single comments) to avoid spamming subscribers with multiple notifications.
 137  * CC in additional reviewers if their second opinion or domain expertise are
 138    needed.
 139  * Follow the review through multiple cycles of updates and re-review with an
 140    aim to getting the merge request landed — a merge request which gets one
 141    round of review and which is then forgotten about is as useful as a merge
 142    request which gets no review at all.
 143  * While it is useful to highlight related areas of the code needing work that
 144    you spot while doing a review, it is not the responsibility of the author of
 145    a merge request to fix things outside the scope of their merge request.
 146    Reviews which increase the scope of work for a merge request make it much
 147    less likely that the merge request will land quickly, which reduces the
 148    effective usefulness of the contribution. This wears down contributors and
 149    reviewers, as they don’t see closure on what they’ve put time into. It is
 150    better to file additional issues for follow-up or related work.
 151  * If you cannot follow through a merge request to completion, unassign yourself
 152    as the reviewer to make this clear to everybody.
 153  * Once a merge request lands, a backport might need to be created for the most
 154    recent stable GLib branch (see the [backport policy](./backports.md). It is
 155    the responsibility of the maintainers to do this, not the responsibility of
 156    the merge request author.
 157