1 files changed, 155 insertions, 0 deletions
diff --git a/docs/bug-mgmt/processes/labels.rst b/docs/bug-mgmt/processes/labels.rst
new file mode 100644
index 0000000000..60c1bbeb2b
--- /dev/null
+++ b/docs/bug-mgmt/processes/labels.rst
@@ -0,0 +1,155 @@
+GitHub Metadata Recommendations
+===============================
+
+To have better consistency with code and task tracking among Mozilla
+Central, Bugzilla, and GitHub, we request that you use a common set of
+labels in your projects. Benefits of improved consistency in our
+conventions include:
+
+-  Consistency makes measurement of processes simpler across the
+   organization
+-  Consistency makes it easier to write reusable process tools
+-  Consistency increases clarity for those than need to work across
+   different repositories and bug trackers
+-  Consistency reduces friction around engineering mobility between
+   projects
+
+We recommend creating sets of labels in your project to do this.
+
+Bug types
+---------
+
+In Bugzilla bugs are distinguished by type: ``defect``, ``enhancement``,
+and ``tasks``. Use a label to make this distinction in your project.
+
+Statuses
+--------
+
+Bugs in GitHub issues have two states: closed and open. Bugzilla has a
+richer set of states.
+
+When you close a bug, add a label indicating `the
+resolution <https://wiki.mozilla.org/BMO/UserGuide/BugStatuses#Resolutions>`__.
+
+-  ``fixed``
+
+   -  A change set for the bug has been landed in Mozilla-Central
+   -  A GitHub issue could be closed, but the change set has not
+      landed so it would be still considered open from the
+      Bugzilla point of view
+
+-  ``invalid``
+
+   -  The problem described is not a bug.
+
+-  ``incomplete``
+
+   -  The problem is vaguely described with no steps to reproduce, or is
+      a support request.
+
+-  ``wontfix``
+
+   -  The problem described is a bug which will never be fixed.
+
+-  ``duplicate``
+
+   -  The problem is a duplicate of an existing bug. Be sure to link the
+      bug this is a duplicate of.
+
+-  ``worksforme``
+
+   -  All attempts at reproducing this bug were futile, and reading the
+      code produces no clues as to why the described behavior would
+      occur.
+
+Severities (Required)
+---------------------
+
+The triage process for Firefox bugs in Bugzilla requires a non default
+value of a bug's :ref:`Severity (definitions) <Defect Severity>`.
+
+Release Status Flags
+--------------------
+
+Open Firefox bugs may also have :ref:`status flags <Release Status Flags>`
+(``status_firefoxNN``) set for Nightly, Beta, Release, or ESR.
+
+Priorities
+----------
+
+Firefox projects in Bugzilla can use the :ref:`priority field <Priority Definitions>`
+to indicate when a bug will be worked on.
+
+Keywords
+--------
+
+In GitHub issues metadata is either a label or the bug’s open/closed
+state.
+
+Some Bugzilla metadata behaves like labels, but you need to be careful
+with how you use it in order not to confuse QA.
+
+Regressions
+~~~~~~~~~~~
+
+In Bugzilla, the ``regression`` keyword indicates a regression in
+existing behavior introduced by a code change.
+
+When a bug is labeled as a regression in GitHub does it imply the
+regression is in the code module in GitHub, or the module that’s landed
+in Mozilla Central? Using the label ``regression-internal`` will signal
+QA that the regression is internal to your development cycle, and not
+one introduced into the Mozilla Central tree.
+
+If it is not clear which pull request caused the regression, add the
+``regressionwindow-wanted`` label.
+
+Other Keywords
+~~~~~~~~~~~~~~
+
+Other useful labels include ``enhancement`` to distinguish feature
+requests, and ``good first issue`` to signal to contributors (`along
+with adequate
+documentation <http://blog.humphd.org/why-good-first-bugs-often-arent/>`__.)
+
+Summary
+-------
+
+To represent Bugzilla fields, use labels following this scheme.
+
+-  Bug types
+
+   -  ``defect``, ``enhancement``, ``task``
+
+-  Resolution statuses
+
+   -  ``invalid``, ``duplicate``, ``incomplete``, ``worksforme``,
+      ``wontfix``
+
+-  Regressions
+
+   -  ``regression``, ``regressionwindow-wanted``,
+      ``regression-internal``
+
+
+-  :ref:`Severity <Defect Severity>` (required)
+
+   -  ``S1``, ``S2``, ``S3``, ``S4``, ``N/A`` (reserved for bugs
+      of type ``task`` or ``enhancement``)
+
+-  :ref:`Status flags <Release Status Flags>`
+
+   -  ``status_firefoxNN:<status>``
+      (example ``status_firefox77:affected``)
+
+-  :ref:`Priority <Priority Definitions>`
+
+   -  ``P1``, ``P2``, ``P3``, ``P5``
+
+-  Other keywords
+
+   -  ``good first bug``, ``perf``, &etc.
+
+
+You may already have a set of tags, so do an edit to convert them
+or use `the GitHub settings app <https://github.com/probot/settings>`__.