docs/bug-mgmt/processes/labels.rst

   1 GitHub Metadata Recommendations
   2 ===============================
   3
   4 To have better consistency with code and task tracking among Mozilla
   5 Central, Bugzilla, and GitHub, we request that you use a common set of
   6 labels in your projects. Benefits of improved consistency in our
   7 conventions include:
   8
   9 -  Consistency makes measurement of processes simpler across the
  10    organization
  11 -  Consistency makes it easier to write reusable process tools
  12 -  Consistency increases clarity for those than need to work across
  13    different repositories and bug trackers
  14 -  Consistency reduces friction around engineering mobility between
  15    projects
  16
  17 We recommend creating sets of labels in your project to do this.
  18
  19 Bug types
  20 ---------
  21
  22 In Bugzilla bugs are distinguished by type: ``defect``, ``enhancement``,
  23 and ``tasks``. Use a label to make this distinction in your project.
  24
  25 Statuses
  26 --------
  27
  28 Bugs in GitHub issues have two states: closed and open. Bugzilla has a
  29 richer set of states.
  30
  31 When you close a bug, add a label indicating `the
  32 resolution <https://wiki.mozilla.org/BMO/UserGuide/BugStatuses#Resolutions>`__.
  33
  34 -  ``fixed``
  35
  36    -  A change set for the bug has been landed in Mozilla-Central
  37    -  A GitHub issue could be closed, but the change set has not
  38       landed so it would be still considered open from the
  39       Bugzilla point of view
  40
  41 -  ``invalid``
  42
  43    -  The problem described is not a bug.
  44
  45 -  ``incomplete``
  46
  47    -  The problem is vaguely described with no steps to reproduce, or is
  48       a support request.
  49
  50 -  ``wontfix``
  51
  52    -  The problem described is a bug which will never be fixed.
  53
  54 -  ``duplicate``
  55
  56    -  The problem is a duplicate of an existing bug. Be sure to link the
  57       bug this is a duplicate of.
  58
  59 -  ``worksforme``
  60
  61    -  All attempts at reproducing this bug were futile, and reading the
  62       code produces no clues as to why the described behavior would
  63       occur.
  64
  65 Severities (Required)
  66 ---------------------
  67
  68 The triage process for Firefox bugs in Bugzilla requires a non default
  69 value of a bug's :ref:`Severity (definitions) <Defect Severity>`.
  70
  71 Release Status Flags
  72 --------------------
  73
  74 Open Firefox bugs may also have :ref:`status flags <Release Status Flags>`
  75 (``status_firefoxNN``) set for Nightly, Beta, Release, or ESR.
  76
  77 Priorities
  78 ----------
  79
  80 Firefox projects in Bugzilla can use the :ref:`priority field <Priority Definitions>`
  81 to indicate when a bug will be worked on.
  82
  83 Keywords
  84 --------
  85
  86 In GitHub issues metadata is either a label or the bug’s open/closed
  87 state.
  88
  89 Some Bugzilla metadata behaves like labels, but you need to be careful
  90 with how you use it in order not to confuse QA.
  91
  92 Regressions
  93 ~~~~~~~~~~~
  94
  95 In Bugzilla, the ``regression`` keyword indicates a regression in
  96 existing behavior introduced by a code change.
  97
  98 When a bug is labeled as a regression in GitHub does it imply the
  99 regression is in the code module in GitHub, or the module that’s landed
 100 in Mozilla Central? Using the label ``regression-internal`` will signal
 101 QA that the regression is internal to your development cycle, and not
 102 one introduced into the Mozilla Central tree.
 103
 104 If it is not clear which pull request caused the regression, add the
 105 ``regressionwindow-wanted`` label.
 106
 107 Other Keywords
 108 ~~~~~~~~~~~~~~
 109
 110 Other useful labels include ``enhancement`` to distinguish feature
 111 requests, and ``good first issue`` to signal to contributors (`along
 112 with adequate
 113 documentation <http://blog.humphd.org/why-good-first-bugs-often-arent/>`__.)
 114
 115 Summary
 116 -------
 117
 118 To represent Bugzilla fields, use labels following this scheme.
 119
 120 -  Bug types
 121
 122    -  ``defect``, ``enhancement``, ``task``
 123
 124 -  Resolution statuses
 125
 126    -  ``invalid``, ``duplicate``, ``incomplete``, ``worksforme``,
 127       ``wontfix``
 128
 129 -  Regressions
 130
 131    -  ``regression``, ``regressionwindow-wanted``,
 132       ``regression-internal``
 133
 134
 135 -  :ref:`Severity <Defect Severity>` (required)
 136
 137    -  ``S1``, ``S2``, ``S3``, ``S4``, ``N/A`` (reserved for bugs
 138       of type ``task`` or ``enhancement``)
 139
 140 -  :ref:`Status flags <Release Status Flags>`
 141
 142    -  ``status_firefoxNN:<status>``
 143       (example ``status_firefox77:affected``)
 144
 145 -  :ref:`Priority <Priority Definitions>`
 146
 147    -  ``P1``, ``P2``, ``P3``, ``P5``
 148
 149 -  Other keywords
 150
 151    -  ``good first bug``, ``perf``, &etc.
 152
 153
 154 You may already have a set of tags, so do an edit to convert them
 155 or use `the GitHub settings app <https://github.com/probot/settings>`__.