Bug 1625216 - Migration the bugzilla doc in-tree from github r=emceeaich

for now, it is just a pandoc -trst conversion and titles added

I will polish the files.

Differential Revision: https://phabricator.services.mozilla.com/D68510

--HG--
extra : moz-landing-system : lando

docs/bug-mgmt/guides/bug-types.rst

+Bug Types
+=========
+
+We organize bugs by type to make it easier to make triage decisions, get
+the bug to the right person to make a decision, and understand release
+quality.
+
+-  **Defect** regression, crash, hang, security vulnerability and any
+   other reported issue
+-  **Enhancement** new feature, improvement in UI, performance, etc. and
+   any other request for user-facing enhancements to the product, not
+   engineering changes
+-  **Task** refactoring, removal, replacement, enabling or disabling of
+   functionality and any other engineering task
+
+All bug types need triage decisions. Engineering `triages defects and
+tasks <triage-bugzilla>`__. Product management `triages
+enhancements <new-feature-triage>`__.
+
+It’s important to distinguish an enhancement from other types because
+they use different triage queues.
+
+Distinguishing between defects and tasks is important because we want to
+understand code quality and reduce the number of defects we introduce as
+we work on new features and fix existing defects.
+
+When triaging, a task can be as important as a defect. A behind the
+scenes change to how a thread is handled can affect performance as seen
+by a user.

docs/bug-mgmt/guides/severity.rst

+Defect severity
+===============
+
+Definition
+----------
+
+We use the ``severity`` field in Bugzilla to indicate the scope of a
+bug's effect on Firefox.
+
+The field is display alongside the bug's priority.
+
+.. image:: screenshot-severity.png
+   :alt: Screenshot of severity field
+
+
+Levels
+------
+
+`Severities are
+enumerated <https://wiki.mozilla.org/BMO/UserGuide/BugFields#severity>`__
+as:
+
+-  ``blocker`` Broken important user-facing feature, Blocks development
+   and/or testing work
+-  ``critical`` Affecting a large number of users (all users on AMD64,
+   Windows, MacOS, Linux), or major areas of functionality (tls, DOM,
+   JavaScript, FxA, Add-ons)
+-  ``normal`` Default; Regular issue, some loss of functionality under
+   specific circumstances
+-  ``minor`` Affecting a small number of users (i.e. ArchLinux users on
+   PowerPC), a problem with an easy workaround, or a cosmetic issue such
+   as misspellings or text alignment
+
+By default, all bugs have a severity of ``normal``.
+
+Rules of thumb
+--------------
+
+-  *A crash may be be a critical defect, but not all crashes are
+   critical defects*
+-  If a bug's severity is ``critical`` or ``blocker`` then it **must**
+   have an ``assignee``
+-  Enhancement bug severity is ``normal``
+
+The ``severity`` field vs the ``tracking_firefoxNN`` field
+----------------------------------------------------------
+
+The ``tracking_firefoxNN`` field is used by Release Management.
+
+A bug with ``tracking_firefoxNN`` of ``blocking`` does not mean the the
+bug's ``severity`` is ``blocking``, just that the bug is needed to be
+``RESOLVED`` as ``FIXED`` or ``VERIFIED`` for a release train.

docs/bug-mgmt/guides/triage-priorities.rst

+Triage Priorities
+=================
+
+Our work *must* be focused on Mozilla’s objectives, and as you triage
+bugs you should prioritize accordingly.
+
+Defects and tasks which affect:
+
+-  Performance
+-  Privacy
+-  User Security
+
+should be the highest priorities.
+
+Performance
+-----------
+
+-  Use the ``perf`` keyword
+-  Add ``[qf:?]`` to the whiteboard if you think the Performance team
+   should look at this bug
+
+Privacy
+-------
+
+-  Use the ``privacy`` keyword
+
+User Security
+-------------
+
+-  Will this bug adversely affect Firefox users if left public?
+
+   -  Add to security group
+
+-  Otherwise move bug to one of:
+
+   -  Core:: Security
+   -  Firefox:: Security
+   -  Toolkit:: Security
+   -  Webkit:: Security

docs/bug-mgmt/index.rst

+Bug Handling
+============
+
+Guides
+------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   guides/*
+
+Policies
+--------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   policies/*
+
+Processes
+---------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   processes/*
+
+Related documentation
+---------------------
+
+-  `bugzilla.mozilla.org documentation <https://bmo.readthedocs.org/>`__
+-  `bugzilla.mozilla.org field
+   defintions <https://wiki.mozilla.org/BMO/UserGuide/BugFields>`__
+-  `Lando
+   documentation <https://moz-conduit.readthedocs.io/en/latest/lando-user.html>`__
+-  `Mozilla Phabricator (Code Review)
+   documentation <https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html>`__

docs/bug-mgmt/policies/feature-flags.rst

+Feature flags
+=============
+
+.. raw:: html
+
+   <p style="color: white; background-color: red;">
+
+**Note**\ *: this policy is obsolete and will be replaced by a unified
+feature tracking policy under development.*
+
+.. raw:: html
+
+   </p>
+
+Product and release need to track bugs whose visibility is controlled
+through a pref. Once a feature has been QAed and approved for a release,
+the preference should be enabled.
+
+Policy
+~~~~~~
+
+*For any feature or fix controlled by a preference flag in Firefox,
+there should be a single bug (e.g. a meta bug) to track its release. If
+the feature requires multiple bugs/patches then this should be a
+``meta`` bug.*
+
+*The bug which tracks a feature or fix that is controlled by a flag in
+Firefox preferences must do the following:*
+
+*It*\ **must**\ *use the ``behind-pref`` flag. The leads for the feature
+would need to update the flags appropriately until the bug is closed.*
+
+*It*\ **should**\ *be added to the Firefox Feature Trello board.*
+
+*It*\ **must**\ *state in a comment or the summary which preference will
+be used to manage visibility.*
+
+*It*\ **must**\ *request the ``qe-verify`` flag (setting it to ``?``)
+and the bug*\ **must**\ *be verfified (Status: RESOLVED, Resolution:
+VERIFIED) by QA once they have accepted the ``qe-verify`` request
+(setting the flag to ``+``) before the feature can be promoted to Beta.*
+
+*The severity of the bug tracking the feature*\ **must**\ *be set to
+``enhancement``.*
+
+*The Release Managers for each train must consent to the feature being
+enabled on that train.*
+
+*QA*\ **must**\ *sign off on the feature before it is enabled in Beta.*
+
+*Any released feature*\ **must**\ *have a value of the parent bug’s
+``behind-pref`` flag set to the version where the feature was released,
+and have a state of VERIFIED and resolution FIXED.*
+
+The ``behind-pref`` flag
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``behind-pref`` flag is a multi-valued release-status flag with the
+values
+
+-  ``---``
+-  ``in-progress``
+-  ``off``
+-  ``releaseNN``
+-  ``betaNN+1``
+-  ``nightlyNN+2``
+
+Where NN is the current release version of Firefox.
+
+Values and Meanings
+^^^^^^^^^^^^^^^^^^^
+
+.. raw:: html
+
+   <dl>
+
+.. raw:: html
+
+   <dt>
+
+—
+
+.. raw:: html
+
+   </dt>
+
+.. raw:: html
+
+   <dd>
+
+This is not a feature that is preffed-off
+
+.. raw:: html
+
+   </dd>
+
+.. raw:: html
+
+   <dt>
+
+in-progress
+
+.. raw:: html
+
+   </dt>
+
+.. raw:: html
+
+   <dd>
+
+One or more bugs implementing the feature are still in progress and the
+feature is not available in any release
+
+.. raw:: html
+
+   </dd>
+
+.. raw:: html
+
+   <dt>
+
+off
+
+.. raw:: html
+
+   </dt>
+
+.. raw:: html
+
+   <dd>
+
+The code for this feature has landed in m-c but the feature is
+preffed-off in all releases
+
+.. raw:: html
+
+   </dd>
+
+.. raw:: html
+
+   <dt>
+
+releaseNN
+
+.. raw:: html
+
+   </dt>
+
+.. raw:: html
+
+   <dd>
+
+Feature was enabled in or will ride the trains to Release NN
+
+.. raw:: html
+
+   </dd>
+
+.. raw:: html
+
+   <dt>
+
+betaNN
+
+.. raw:: html
+
+   </dt>
+
+.. raw:: html
+
+   <dd>
+
+The feature was enabled in Beta NN and Nightly but not riding train to
+Release
+
+.. raw:: html
+
+   </dd>
+
+.. raw:: html
+
+   <dt>
+
+nightlyNN
+
+.. raw:: html
+
+   </dt>
+
+.. raw:: html
+
+   <dd>
+
+The feature was enabled in Nightly NN only
+
+.. raw:: html
+
+   </dd>
+
+.. raw:: html
+
+   </dl>
+
+Maintenance
+^^^^^^^^^^^
+
+If, as of release version 60, current values of the flag were:
+
+-  ``release60``
+-  ``release61``
+-  ``release62``
+-  ``beta61``
+-  ``beta62``
+-  ``nightly62``
+
+on merge day we would add
+
+-  ``release63``
+-  ``beta63``
+-  ``nightly63``
+
+and disable (but not delete) ``release60``, ``beta61``, and
+``nightly62``.
+
+ESR
+^^^
+
+For tracking the feature in ESR, we create a ``behind-pref-esr`` status
+flag. It will be kept up with the values of the current, previous, and
+next ESR releases.
+
+*Example*
+
+-  ``---``
+-  ``off``
+-  ``esr52``
+-  ``esr60``
+-  ``esr72``
+
+Example
+~~~~~~~
+
+A bug is filed, “Make Tabby Cats the default new tab experience.” And
+the team developing this (engineering and product) decide that this
+should be controlled behind a preference,
+``browser.newtabpage.default.tabbycat``. The developers break the work
+for this feature down into three bugs. A fourth bug will be used to
+track the preference flag.
+
+-  The bug’s summary is updated to
+   ``[meta] Make Tabby Cats the default new tab experience``
+-  A comment is filed listing the name of the preference
+-  The ``behind-pref`` flag is set to ``in-progress``
+-  The bug’s severity is set to ``enhancement``
+-  The three implementation bugs and the pref bug should be marked as
+   blocking the ``[meta]`` bug for the new feature
+
+As the feature is developed and the individual patches implement it
+land, it’s kept off by compiler directives, the pref, or both. As these
+land, and are not backed out, these bugs can be marked RESOLVED FIXED.
+
+The lead for the feature–which may be an engineer, a program manager, or
+a product manager–must notify the Nightly Release Manager before
+enabling it.
+
+-  The bug’s ``behind-pref`` flag is set to ``nightlyNN`` where NN is
+   the current version of nightly to indicate it’s now available in
+   nightly
+-  The ``qe-verify`` flag is set to +, requesting QA’s attention
+
+Before the feature can graduate to Beta, it must be verified by QA.
+
+-  The feature is tested on nightly and confirmed to work as specified
+   (implicit here is the feature team’s involvement in creating a test
+   plan)
+
+If the feature does not pass testing then QA should file bugs blocking
+the ``[meta]`` bug for the feature. QA and the development team must
+confer and decide if the feature will be disabled in Nightly, or allowed
+to be kept on while bugs are fixed. This will depend on risk and
+severity of the bugs found.
+
+If it’s decided to disable the feature, then it should be turned off in
+the nightly build and the ``behind-pref`` flag set to ``off``. The bug’s
+comments should explain how that decision was reached. Once the defects
+have been resolved, then ``behind-pref`` can be reset to ``nightlyNN``.
+
+Once the feature has been verfied by QA then:
+
+-  The bug should be enabled in Beta once Release Management approves
+-  the ``behind-pref`` flag is updated to ``releaseNN`` where NN is the
+   next release.
+
+Once the patch for the bug to enable in Beta lands:
+
+-  QA moves the bug’s status to VERIFIED and resolution to FIXED
+
+The feature now *rides the trains* to release. The bug is then
+considered completed.
+
+If it’s decided to hold the feature out of the next release and let Beta
+users try it out, then the ``behind-pref`` flag is set to ``betaNN``
+where NN is the next beta. Once the decision is made to let the feature
+ride the trains, then it is updated to ``releaseNN`` where NN is the
+target release.
+
+When the feature is merged to ESR the ``behind-pref-esr`` field should
+be set to the version where it will be released.
+
+Questions
+~~~~~~~~~
+
+What if we turn off the feature in the main release?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The main bug’s ``behind-pref`` value should be reset to the releases
+it’s still on, ``betaNN+1`` or ``nightlyNN+2``; or to ``off``, and the
+bug’s status set to REOPENED.
+
+The bug to turn off the feature must be a dependency of the main bug.
+
+What about bugs found in a feature after release
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These bugs do not need the ``behind-pref`` flag. If it’s decided that
+the feature should be turned off until the bug or bugs are fixed, then
+these bugs should block the original feature tracking bug.
+
+What if we want to hold a feature over a release cycle and not promote it?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On merge day, the ``behind-pref`` flag would retain it’s earlier value,
+and remain preffed off in other versions.
+
+What if I want to enable parts of my feature in Nightly?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your feature is incomplete, but some functionality is available, then
+mark ``behind-pref`` as ``nightlyNN`` where NN is the current nighty
+version. Do not request ``qe-verify`` until the feature is complete.
+
+If you plan to incrementally add functionality to Nightly over a number
+of release cycles, then you can use a single ``meta`` bug to keep track
+of functionality, but don’t promote the feature to ``Beta``.
+
+If you intend to implement functionality over a number of Beta and
+Release cycles, then the tracking/meta bug should not be marked as FIXED
+VERIFIED until the feature is completed.
+
+What about gradual rollout of features
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you intend to roll out the feature gradually, then the rollout should
+be tracked in the feature bug’s comments. If the the rollout percentage
+is controlled by a preference, then changes to that preference should be
+blockers of the the feature bug.
+
+Tracking queries
+~~~~~~~~~~~~~~~~
+
+-  Open bugs for features behind preferences
+-  Open bugs for features behind preferences landed but not QAed
+-  Bugs for features in upcoming release
+-  Bugs for features which have been disabled

docs/bug-mgmt/policies/new-feature-triage.rst

+New Feature Triage
+==================
+
+Identifying Feature Requests
+----------------------------
+
+Bugs which request new features or enhancements should be of
+type=\ ``enhancement``.
+
+Older bugs may also be feature requests if some or all of the following
+are true:
+
+-  ~Bugs marked severity = ``enhancement``\ ~ *(This has gone away with
+   the switch to*\ `bug
+   types <https://bugzilla.mozilla.org/show_bug.cgi?id=1522340>`__\ *)*
+-  Bugs with ``feature`` or similar in whiteboard or short description
+-  ``[RFE]`` in whiteboard, short description, or description
+-  Bugs not explicitly marked as a feature request, but appear to be
+   feature requests
+-  Bugs marked with ``feature`` keyword
+
+Initial Triage
+--------------
+
+Staff, contractors, and other contributors looking at new bugs in
+*Firefox::Untriaged* and *::General* components should consider if a
+bug, if not marked as a feature request, should be one, and if so:
+
+-  Update the bug’s type to ``enhancement``
+-  Determine which product and component the bug belongs to and update
+   it **or**
+
+   -  Use *needinfo* to ask a component’s triage owner or a module’s
+      owner where the request should go
+
+Product Manager Triage
+----------------------
+
+-  The product manager for the component reviews bugs of type
+   ``enhancement``
+
+   -  This review should be done a least weekly
+
+-  Reassigns to another Product::Component if necessary **or**
+-  Determines next steps
+
+   -  Close bug as ``RESOLVED WONTFIX`` with comment as to why and
+      thanking submitter
+   -  If bug is similar enough to work in roadmap, close bug as
+      ``RESOLVED DUPLICATE`` of the feature bug it is similar to
+
+      -  If there’s not a feature bug created already, then consider
+         making this bug the feature bug
+
+         -  Set type to ``enhancement``
+
+   -  Set bug to ``P5`` priority with comment thanking submitter, and
+      explaining that the request will be considered for future roadmaps

docs/bug-mgmt/policies/regressions-github.rst

+Regressions from GitHub
+=======================
+
+Release Management and the weekly regression triage must be aware of the
+status of all reported regressions in order to assure we are not
+shipping known regressions in Firefox releases.
+
+If a team is using GitHub to manage their part of the Firefox project,
+there’s a risk that those groups might not see a regression.
+
+We need an agreed to standard for how we keep track of these.
+
+Policy
+------
+
+*All Firefox components, even if their bugs are tracked off of Bugzilla,
+must have a component in Bugzilla.*
+
+*If a regression bug is found in any of the release trains (Nightly,
+Beta, Release, or ESR) and the bug is in a Firefox component which uses
+an external repository, the regression must be tracked by a bug in
+Bugzilla (whether or not the component in question uses an external
+issue tracker).*
+
+*Unless approved by Release Management, any GitHub managed code with
+open regressions will not be merged to mozilla-central. Even if the
+regression is not code that has been previously merged into
+mozilla-central.*
+
+*All Firefox code managed in GitHub which uses GitHub to manage
+issues*  `must use the shared
+tags <https://mozilla.github.io/bmo-harmony/labels>`__.
+
+Comments
+~~~~~~~~
+
+The bug **must** have the regression keyword.
+
+The bug **must** have release flags set.
+
+If the team works in an external bug tracker, then the Bugzilla bug
+**must** reference, using the see-also field, the URL of the bug in the
+external tracker.
+
+The bug **must not** be RESOLVED until the code from the external
+repository containing the change set for the bug has landed in
+mozilla-central. When the change set lands in mozilla-central, the
+Bugzilla tracking bug should be set to RESOLVED FIXED and release status
+flags should be updated to reflect the release trains the fix has been
+landed or uplifted into.
+
+If the change set containing the patch for the regression is reverted
+from mozilla-central, for any reason, then the tracking bug for the
+regression **must** be set to REOPENED and the release status flags
+updated accordingly.
+
+If the change set containing the patch for the bug is backed out, for
+any reason, the bug must be reopened and the status flags on the
+Bugzilla tracking bug updated.
+
+The team responsible for the component with the regression **should**
+strive to create a patch for mozilla-central which contains the fix for
+the bug alone, not a monolithic patch containing changes for several
+other bugs or features.
+
+Landings of third-party libraries `must contain a manifest
+file <https://docs.google.com/document/d/12ihxPXBo9zBBaU_pBsPrc_wNHds4Upr-PwFfiSHrbu8>`__.
+
+Best Practices
+--------------
+
+You must file a regression bug in Bugzilla
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*If the code with the regression has landed in mozilla-central, you must
+file a regression bug.*
+
+Example
+^^^^^^^
+
+While using a release of Firefox (Nightly, Beta, Release, ESR) you run
+across a bug. Upon research using MozRegression or other tools you find
+that the bug was introduced in a change set imported from a component
+whose code and issues are managed in GitHub.
+
+Actions to take
+'''''''''''''''
+
+-  Open a new bug in Bugzilla in appropriate component and add the
+   REGRESSION keyword
+-  Set affected status for the releases where the bug appears
+-  Open an issue in the corresponding GitHub project, put the Bugzilla
+   bug number in the title with the prefix ‘Bug’ (i.e. “Bug 99999:
+   Regression in foo”)
+-  Add the REGRESSION label to the new issue
+-  Add the link to the GitHub issue into the ‘See Also” field in the
+   Bugzilla bug
+
+Consequences
+''''''''''''
+
+*Until the regression is fixed or backed out of the GitHub repo, the
+project cannot merge code into mozilla-central*
+
+Example
+^^^^^^^
+
+You import a development branch of a component managed in GitHub into
+your copy of master. You find a bug and isolate it to the imported
+branch. The code is managed in their own GitHub project, but bugs are
+managed in Bugzilla.
+
+Actions to take
+'''''''''''''''
+
+-  Open a new bug in Bugzilla in appropriate component and add the
+   REGRESSION keyword
+-  Set affected status for the releases where the bug appears
+
+Consequences
+''''''''''''
+
+*Until the regression is fixed or backed out of the GitHub repo, the
+project cannot merge code into mozilla-central*
+
+Do not file a regression bug in Bugzilla
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*If the code with the regression has not landed in mozilla-central, you
+do not need to file a bug.*
+
+
+Example
+^^^^^^^
+
+You import a development branch of a component managed in GitHub into
+your copy of master. You find a bug and isolate it to the imported
+branch. The code and issues are managed in their own GitHub project.
+
+
+Actions to take
+'''''''''''''''
+
+-  File new issue in the GitHub repository of the imported code.
+-  Label issue as REGRESSION
+
+Consequence
+'''''''''''
+
+*Issue blocks merge of GitHub project with mozilla-central until
+resolved or backed out.*

docs/bug-mgmt/policies/triage-bugzilla.rst

+Triage for Bugzilla
+===================
+
+Expectations
+------------
+
+All teams working on Firefox using either or both Mozilla-central and
+Bugzilla are expected to follow the following process.
+
+Why Triage
+----------
+
+We want to make sure that we looked at every defect and a priority has
+been defined. This way, we make sure that we did not miss any critical
+issues during the development and stabilization cycles.
+
+Staying on top of the bugs in your component means:
+
+-  You get ahead of critical regressions and crashes which could trigger
+   a point release if uncaught
+
+   -  And you don’t want to spend your holiday with the Release
+      Management team (not that they don’t like you)
+
+-  Your bug queue is not overwhelming
+
+   -  Members of your team do not see the bug queue and get the
+      ‘wiggins’
+
+Who Triages
+-----------
+
+Engineering managers and directors are responsible for naming the
+individuals responsible for triaging `defect and task
+bugs <bug-types>`__ in a component.
+
+We use Bugzilla to track this. See the `list of triage
+owners <https://bugzilla.mozilla.org/page.cgi?id=triage_owners.html>`__.
+
+If you need to change who is responsible for triaging a bug in a
+component, please `file a bug against bugzilla.mozilla.org in the
+Administration
+component <https://bugzilla.mozilla.org/enter_bug.cgi?product=bugzilla.mozilla.org&component=Administration>`__.
+When a new component is created, a triage owner **must** be named.
+
+Rotating triage
+~~~~~~~~~~~~~~~
+
+Some components are monitored by a rotation of triagers. In those cases,
+the triage owner should be seen as the person responsible for assuring
+the component is triaged, but the work is done by the people in the
+rotation. The `rotations are managed as
+calendars <https://github.com/mozilla/relman-auto-nag/tree/master/auto_nag/scripts/configs>`__.
+
+If you wish to set up a rotation for triaging one or more components,
+contact the Bugzilla team on Slack (#bmo.)
+
+Firefox::General and Toolkit::General
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Bugs in Firefox::General are fitted with Bug Bug’s model to see if
+there’s another component with a high liklihood of fit, and if a
+threshold confidence is achived, the bug is moved to that component.
+
+Members of the community also review bugs in this component and try to
+move them to a component.
+
+There are also two, rotating triagers for the component. They review the
+remaining bugs over the course of a month and move them if possible.
+
+To volunteer for this rotation, contact the Bugzilla team on Slack
+(#bmo.)
+
+What Do You Triage
+------------------
+
+As a triage owner the queries you should be following for your component
+are:
+
+-  All open bugs, in your components without a pending ``needinfo`` flag
+   or a ``stalled`` keyword since start of current release cycle which
+   do not have a priorty set
+-  All bugs with active review requests in your component which have not
+   been modified in five days
+-  All bugs with reviewed, but unlanded patches in your components
+-  All bugs with a needinfo request unanswered for more than 10 days
+
+There’s a tool to help you find bugs
+https://mozilla.github.io/triage-center/ and the source is at
+https://github.com/mozilla/triage-center/.
+
+These bugs are reviewed in the weekly Regression Triage meeting \* Bugs
+of type ``defect`` with the ``regression`` keyword without
+-status-firefoxNN decisions \* Bugs of type ``defect`` with the
+``regression`` keyword without a regression range
+
+If a bug is an enhancement it needs a priority set and a target release
+or program milestone. These bugs are normally reviewed by product
+managers. Enhancements can lead to release notes and QA needed that we
+also need to know about
+
+If a bug is a task resulting in a changeset, release managers will need
+to known when this work will be done. A task such as refactoring fragile
+code can be risky.
+
+Weekly or More Frequently (depending on the component) find `un-triaged
+bugs in the components you
+triage <https://bugzilla.mozilla.org/buglist.cgi?f1=triage_owner&bug_type=defect&o1=equals&resolution=---&priority=--&v1=%25user%25>`__.
+
+For each bug decide priority (you can override what’s already been set,
+as a triage lead, you are the decider.)
+
++----------------------------------------+-----------------------------+
+| Priority                               | Description                 |
++========================================+=============================+
+| –                                      | No decision                 |
++----------------------------------------+-----------------------------+
+| P1                                     | Fix in the current release  |
+|                                        | cycle                       |
++----------------------------------------+-----------------------------+
+| P2                                     | Fix in the next release     |
+|                                        | cycle or the following      |
+|                                        | (nightly + 1 or nightly +   |
+|                                        | 2)                          |
++----------------------------------------+-----------------------------+
+| P3                                     | Backlog                     |
++----------------------------------------+-----------------------------+
+| P4                                     | Do not use, this priority   |
+|                                        | is for web platform test    |
+|                                        | bots                        |
++----------------------------------------+-----------------------------+
+| P5                                     | Will not fix, but will      |
+|                                        | accept a patch              |
++----------------------------------------+-----------------------------+
+
+What About Release Status (status_firefoxNN) Flags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Release status (and tracking) flags are set independent of triage
+decisions, but should be consistent with triage decisions.
+
+Also, as a release approaches, the release status of open, high priority
+(P1) bugs can change. Triagers and engineering leads must review open
+bugs with a release status of affected and fix_optional, and decide
+which of these to keep, and move the others to wontfix for the current
+cycle.
+
+The flag ``status_firefoxNN`` has many values, here’s a cheat sheet.
+
+== ========== ========== ============ =================
+—  ?          unaffected affected     fixed
+== ========== ========== ============ =================
+?  unaffected            wontfix      verified
+\  affected              fix-optional disabled
+\                        fixed        verified-disabled
+== ========== ========== ============ =================
+
+The headers of the table are values of the status flag. Each column are
+the states reachable from the column headings.
+
+-  “—” we don’t know whether Firefox N is affected
+-  “?” we don’t know whether Firefox N is affected, but we want to find
+   out.
+-  “affected” - present in this release
+-  “unaffected” - not present in this release
+-  “fixed” - a contributor has landed a fix to address the issue
+-  “verified” - the fix has been verified by QA or other contributors
+-  “disabled” - the fix or the feature has been backed out or disabled
+-  “verified disabled” - QA or other contributors confirmed the fix or
+   the feature has been backed out or disabled
+-  “wontfix” - we have decided not to accept/uplift a fix for this
+   release cycle (it is not the same as the bug resolution WONTFIX).
+   This can also mean that we don’t know how to fix that and will ship
+   with this bug
+-  “fix-optional” - we would take a fix for the current release but
+   don’t consider it as important/blocking for the release
+
+Automatic Triage Overrides
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a bug is tracked for a release, i.e. the ``tracking_firefoxNN``
+flag is set to ``+`` or ``blocking`` triage decisions will be overriden,
+or made as follows:
+
+-  If a bug is tracked for or blocking beta, release or ESR, its
+   priority will be set to ``P1``
+-  If a bug is tracked for or blocking nightly, its priority will be set
+   to ``P2``
+
+Because bugs can be bumped in priority it’s essential that triage owners
+review their
+`P1 <https://bugzilla.mozilla.org/buglist.cgi?priority=P1&f1=triage_owner&o1=equals&resolution=---&v1=%25user%25>`__
+and
+`P2 <https://bugzilla.mozilla.org/buglist.cgi?priority=P2&f1=triage_owner&o1=equals&resolution=---&v1=%25user%25>`__
+bugs frequently.
+
+Questions and Edge Cases
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This bug is a feature request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set the bug’s type to ``enhancement``, add the ``feature`` keyword if
+relevant, and state to ``NEW``. This bug will be excluded from future
+triage queries.
+
+This bug is a task, not a defect
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set the bug’s type to ``task``, and state to ``NEW``. This bug will be
+excluded from future triage queries.
+
+If you are not sure of a bug’s type, check `our rules for bug
+types <task-defect-enhancement>`__.
+
+This bug’s state is ``UNCONFIRMED``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Are there steps to reproduce? If not, needinfo the person who filed the
+bug, requesting steps to reproduce. You are not obligated to wait
+forever for a response, and bugs for which open requests for information
+go unanswered can be ``RESOLVED`` as ``INCOMPLETE``.
+
+I need help reproducing the bug
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set a needinfo for the QA managers, Softvision project managers, or the
+QA owner of the component of the bug.
+
+I don’t have enough information to make a decision
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you don’t have a reproduction or confirmation, or have questions
+about how to proceed, ``needinfo`` the person who filed the bug, or
+someone who can answer.
+
+The ``stalled`` keyword
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The extreme case of not-enough-information is one which cannot be
+answered with a ``needinfo`` request. The reporter has shared all they
+know about the bug, we are out of strategies to take to resolve it, but
+the bug should be kept open.
+
+Mark the bug as stalled by adding the ``stalled`` keyword to it. The
+keyword will remove it from the list of bugs to be triaged.
+
+If a patch lands on a ``stalled`` bug, automation will remove the
+keyword. Otherwise, when the ``keyword`` is removed, the bug will have
+its priority reset to ``--`` and the components triage owner notified by
+automation.
+
+Bugs which remain ``stalled`` for long periods of time should be
+reviewed, and closed if necessary.
+
+This doesn’t fit into a P1, P2, P3, P4, or P5 framework
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Mark it as a P3.
+
+If it’s a tracking bug, make sure has “[meta]” in the title and has the
+``meta`` keyword added. This will remove it from the list of untriaged
+bugs.
+
+Bug is in the wrong Component
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Remove any priority set, then either move to what you think is the
+correct component, or needinfo the person responsible for the component
+to ask them.
+
+I don’t think we should work on it at any time
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you’ll accept a patch, mark it as P5, otherwise, close it as WONTFIX
+
+My project is on GitHub
+^^^^^^^^^^^^^^^^^^^^^^^
+
+We have `a guide for GitHub projects to follow </labels>`__ when
+triaging.
+
+Watch open needinfo flags
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Don’t let open needinfo flags linger for more than two weeks.
+
+Close minor bugs with unresponded needinfo flags.
+
+Follow up on needinfo flag requests.
+
+The tool will help you find these (the query is imperfect.)
+
+End of Iteration/Release Cycle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Review P1s
+^^^^^^^^^^
+
+Are there unresolved P1s?
+
+Revisit their priority, and move to backlog (P3.)
+
+Review P2s
+^^^^^^^^^^
+
+Are there P2s that should move to P1s for the next cycle?
+
+Are there P2s you now know are lower priority, move to P3.
+
+Review P3s
+^^^^^^^^^^
+
+Are there P3 bugs you now know you won’t get to? Either demote to P5
+(will accept patch) or resolve as WONTFIX.
+
+Tools
+-----
+
+Triage with me
+~~~~~~~~~~~~~~
+
+   One tool we use in addons is triage-with-me. Its a Firefox Add-on
+   that sends all the pages you click on in bugzilla into a server which
+   then sends the URL to everyone else in the triage. – Andy McKay
+
+The upshot is, one person clicks on links in Bugzilla, the bugs open up
+on everyone else’s computer.
+
+-  https://addons.mozilla.org/en-US/firefox/addon/triage-with-me/.
+-  http://www.agmweb.ca/2013-09-06-triage/
+-  http://www.agmweb.ca/2015-03-10-triage-with-me-update/
+
+Questions
+---------
+
+-  Ask in #bugmasters on irc.mozilla.org
+-  Email emceeaich@mozilla.com

docs/bug-mgmt/processes/doc-requests.rst

+User documentation requests
+===========================
+
+If you are working on a change (bugfix, enhancement, or feature) which
+would benefit from user-facing documenation, please use the
+``user-doc-firefox`` flag to request it.
+
+This flag can be modified by anyone with ``EDITBUGS`` privileges.
+
+.. figure:: /public/images/sumo-flag.png
+   :alt: Image of flag in tracking section of bug
+
+   Image of flag in tracking section of bug
+
+The default value of the flag is ``---``.
+
+If the bug needs user-facing documentation, set the flag to
+``docs-needed``. This flag will be monitored by the support.mozilla.org
+(SUMO) team.
+
+Once the docs are ready to be published, set the flag to
+``docs-completed``.
+
+If it’s determined that documentation is not need after setting the flag
+to ``docs-needed``, update the flag to ``none-needed`` so we know that
+it’s been reviewed.
+
+Summary
+-------
+
+=========== == ==============
+From           To
+=========== == ==============
+—           to none-needed
+—           to docs-needed
+docs-needed to none-needed
+docs-needed to docs-completed
+=========== == ==============
+
+Notes
+-----
+
+A flag is used instead of the old keywords because flags can be
+restricted to a subset of products and components.

docs/bug-mgmt/processes/labels.rst

+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 re-usable 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
+
+Several of you are doing this already. But we need you to do some tuning
+of your process.
+
+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>`__.
+
+-  ``invalid``
+
+   -  The problem described is not a bug.
+
+-  ``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. incomplete
+   -  The problem is vaguely described with no steps to reproduce, or is
+      a support request.
+
+Priorities
+----------
+
+Firefox projects in Bugzilla use the priority field to indicate when and
+if a bug will be worked on.
+
+Use these labels in your project to indicate priorities.
+
+-  ``P1``
+
+   -  Fix in the current release or iteration
+
+-  ``P2``
+
+   -  Fix in the next release or iteration
+
+-  ``P3``
+
+   -  Backlog
+
+-  ``P5``
+
+   -  Will not fix, but will accept a patch
+
+You probably already have a set of tags, so do an edit to convert them
+or use `the GitHub settings app <https://github.com/probot/settings>`__.
+
+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/>`__.)
+
+Status Flags
+------------
+
+Bugzilla uses a set of status flags to communicate priorities between
+contributors, product managers, and the the release management team.
+
+A bug which contributors consider a high priority may not effect the
+current release, and vice versa.
+
+In Bugzilla, status for each release number is represented by a field
+which takes `one of multiple
+values <https://wiki.mozilla.org/Bugmasters/Process/Triage/Release_Status>`__.
+
+It’s recommended that you don’t use status and tracking flag tags in
+GitHub issues and use another tool such a Trello or a worksheet to
+communicate to Release Drivers on work that needs to land in the
+``mozilla-centra1`` repository.
+
+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``
+
+-  Priority
+
+   -  ``P1``, ``P2``, ``P3``, ``P5``
+
+-  Other keywords
+
+   -  ``good first bug``, ``perf``, &etc.

docs/bug-mgmt/processes/regressions.rst

+How to Mark Regressions
+=======================
+
+Regressions
+-----------
+
+For regression bugs in Mozilla-Central, our policy is to tag the bug as
+a regression, identify the commits which caused the regression, then
+mark the bugs associated with those commits as causing the regression.
+
+What is a regression?
+---------------------
+
+A regression is a bug (in our scheme a ``defect``) introduced by a
+`changeset <https://en.wikipedia.org/wiki/Changeset>`__.
+
+-  Bug 101 *fixes* Bug 100 with Change Set A
+-  Bug 102 *reported which describes previously correct behavior now not
+   happening*
+-  Bug 102 *investigated and found to be introduced by Change Set A*
+
+Marking a Regression Bug
+------------------------
+
+These things are true about regressions:
+
+-  **Bug Type** is ``defect``
+-  **Keywords** include ``regression``
+-  **Status_FirefoxNN** is ``affected`` for each version (in current
+   nightly, beta, and release) of Firefox in which the bug was found
+-  The bug’s description covers previously working behavior which is no
+   longer working [ed. I need a better phrase for this]
+
+Until the change set which caused the regression has been found through
+`mozregression <https://mozilla.github.io/mozregression/>`__ or another
+bisection tool, the bug should also have the ``regressionwindow-wanted``
+keyword.
+
+Once the change set which caused the regression has been identified,
+remove the ``regressionwindow-wanted`` keyword and set the **Regressed
+By** field to the id of the bug associated with the change set.
+
+Setting the **Regressed By** field will update the **Regresses** field
+in the other bug.
+
+Set a needinfo for the author of the regressing patch asking them to fix
+or revert the regression.
+
+Previous Method
+---------------
+
+Previously we over-loaded the **Blocks** and **Blocked By** fields to
+track the regression, setting **Blocks** to the id of the bug associated
+with the change set causing the regression, and using the
+``regression``, ``regressionwindow-wanted`` keywords and the status
+flags as described above.
+
+This made it difficult to understand what was a dependency and what was
+a regression when looking at dependency trees in Bugzilla.
+
+FAQs
+----
+
+*To be written*

docs/bug-mgmt/processes/shared-bug-queues.rst

+Shared Bug Queues
+=================
+
+Reviewers for change sets can be suggested at the product and component
+level, but only the person who has been asked to review code will be
+notified.
+
+Realizing that Bugzilla users can *watch* other users, `Chris
+Cooper <https://mozillians.org/en-US/u/coop/>`__ came up with the idea
+of having `a shared reviews alias for review
+requests <http://coopcoopbware.tumblr.com/post/170952242320/experiments-in-productivity-the-shared-bug-queue>`__.
+
+If you want to watch a particular part of the tree in Mozilla Central,
+then `use the Herald
+tool <https://phabricator.services.mozilla.com/book/phabricator/article/herald/>`__.
+
+Process
+-------
+
+1. Create a new bugzilla.mozilla.com account for an address which can
+   receive mail.
+
+-  Use the ``name+extension@domain.tld`` trick such as
+   ``jmozillian+reviews@mozilla.com`` to create a unique address
+2. Respond to the email sent by Bugzilla and set a password on the
+   account
+3. `Open a bug <https://mzl.la/2Mg8Sli>`__ to convert the account to a
+   bot and make it the shared review queue for your component
+4. BMO administrator updates the email address of the new account to the
+   ``@mozilla.bugs`` address
+5. BMO administrator updates the default reviewer for the component
+   requested and sets it to the shared review account
+6. Reviewers `follow the shared review account in
+   bugzilla <https://bugzilla.mozilla.org/userprefs.cgi?tab=email>`__
+7. Reviewers get notified when shared review account is ``r?``\ ed

docs/config.yml

@@ -5,6 +5,7 @@
 categories:
     contributing_doc:
         - contributing
+        - bug-mgmt
     source_doc:
         - browser
         - dom

moz.build

@@ -191,4 +191,6 @@ SPHINX_TREES['contributing'] = 'docs/contributing'
 
 SPHINX_TREES['code-quality'] = 'docs/code-quality'
 
+SPHINX_TREES['bug-mgmt'] = 'docs/bug-mgmt'
+
 include('build/templates.mozbuild')