1GitHub Metadata Recommendations
2===============================
3
4To have better consistency with code and task tracking among Mozilla
5Central, Bugzilla, and GitHub, we request that you use a common set of
6labels in your projects. Benefits of improved consistency in our
7conventions include:
8
9-  Consistency makes measurement of processes simpler across the
10   organization
11-  Consistency makes it easier to write re-usable 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
17We recommend creating sets of labels in your project to do this.
18
19Bug types
20---------
21
22In Bugzilla bugs are distinguished by type: ``defect``, ``enhancement``,
23and ``tasks``. Use a label to make this distinction in your project.
24
25Statuses
26--------
27
28Bugs in GitHub issues have two states: closed and open. Bugzilla has a
29richer set of states.
30
31When you close a bug, add a label indicating `the
32resolution <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
65Severities (Required)
66---------------------
67
68The triage process for Firefox bugs in Bugzilla requires a non default
69value of a bug's :ref:`Severity (definitions) <Defect Severity>`.
70
71Release Status Flags
72-------------------------------
73
74Open Firefox bugs may also have :ref:`status flags <Release Status Flags>`
75(``status_firefoxNN``) set for Nightly, Beta, Release, or ESR.
76
77Priorities
78----------
79
80Firefox projects in Bugzilla can use the :ref:`priority field <Priority Definitions>`
81to indicate when a bug will be worked on.
82
83Keywords
84--------
85
86In GitHub issues metadata is either a label or the bug’s open/closed
87state.
88
89Some Bugzilla metadata behaves like labels, but you need to be careful
90with how you use it in order not to confuse QA.
91
92Regressions
93~~~~~~~~~~~
94
95In Bugzilla, the ``regression`` keyword indicates a regression in
96existing behavior introduced by a code change.
97
98When a bug is labeled as a regression in GitHub does it imply the
99regression is in the code module in GitHub, or the module that’s landed
100in Mozilla Central? Using the label ``regression-internal`` will signal
101QA that the regression is internal to your development cycle, and not
102one introduced into the Mozilla Central tree.
103
104If it is not clear which pull request caused the regression, add the
105``regressionwindow-wanted`` label.
106
107Other Keywords
108~~~~~~~~~~~~~~
109
110Other useful labels include ``enhancement`` to distinguish feature
111requests, and ``good first issue`` to signal to contributors (`along
112with adequate
113documentation <http://blog.humphd.org/why-good-first-bugs-often-arent/>`__.)
114
115Summary
116-------
117
118To 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 <Firefox 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
154You may already have a set of tags, so do an edit to convert them
155or use `the GitHub settings app <https://github.com/probot/settings>`__.
156