Start a "what are all of these labels for?" doc

doc/topics/development/labels.rst

@@ -0,0 +1,202 @@
+.. _labels-and-milestones:
+
+============================
+GitHub Labels and Milestones
+============================
+
+SaltStack uses several labeling schemes, as well as applying milestones, to triage incoming issues and pull requests in
+the GitHub Issue Tracker. Most of the labels and milestones are used for internal tracking, but the following
+definitions might prove useful for the community to discover the best issues to help resolve.
+
+Milestones
+==========
+
+Milestones are most often applied to issues, as a milestone is assigned to every issue that has been triaged. However,
+milestones can also be applied to pull requests. SaltStack uses milestones to track bugs or features that should be
+included in the next major feature release, or even the next bug-fix release, as well as what issues are ready to be
+worked on or what might be blocked. All incoming issues must have a milestone associated with them.
+
+Approved
+    Used to indicate that this issue has all of the needed information and is ready to be worked on.
+
+Blocked
+    Used to indicate that the issue is not ready to be worked on yet. This typically applies to issues that have been
+    labeled with “Info Needed”, “Question”, “Expected Behavior”, “Won’t Fix for Now”, etc.
+
+Dot or Bug-fix Release
+    Used to help filter/identify what issues must be fixed before the release such as 2014.7.4 or 2015.2.3. This
+    milestone is often used in conjunction with the ``Blocker`` label, but not always.
+
+Feature Release
+    Similar to the Dot or Bug-fix Release milestone, but for upcoming feature releases such as Boron, Carbon, etc.
+    This milestone is often used in conjunction with the ``Blocker`` label, but not always.
+
+Labels
+======
+
+Labels are used to facilitate the resolution of new pull requests and open issues. Most labels are confined to being
+applied to either issues or pull requests, though some labels may be applied to both.
+
+Issue Labels
+------------
+
+Feature Requests
+~~~~~~~~~~~~~~~~
+
+Bugs
+~~~~
+
+All bugs should have the ``Bug`` label as well as a severity, priority, functional area, and a status, as applicable.
+
+Severity
+^^^^^^^^
+
+How severe is the bug? SaltStack uses four labels to determine the severity of a bug: ``Blocker``, ``Critical``,
+``High``, and ``Medium``. This scale is intended to make the bug-triage process as objective as possible.
+
+Blocker
+    Should be used sparingly to indicate must-have fixes for the impending release.
+
+Critical
+    Applied to bugs that have data loss, crashes, hanging, unresponsive system, or have no workaround.
+
+High Severity
+    Any bug report that contains incorrect functionality, bad functionality, a confusing user experience, or has a
+    possible workaround.
+
+Medium Severity
+    Applied to bugs that are about cosmetic items, spelling, spacing, colors, etc.
+
+Priority
+^^^^^^^^
+
+In addition to using a bug severity to classify issues, a priority is also assigned to each bug to give further
+granularity in searching for bugs to fix. In this way, a bug's priority is defined as follows:
+
+P1
+    Very likely. Everyone will see the bug.
+
+P2
+    Somewhat likely. Most will see the bug, but a few will not.
+
+P3
+    Half will see the bug, about half will not.
+
+P4
+    Most will not see the bug. Usually a very specific use case or corner case.
+
+.. note::
+
+    A bug's priority is relative to its functional area. If a bug report, for example, about ``gitfs`` includes details
+    indicating that everyone who ``gitfs`` will run into this bug, then a ``P1`` label will be applied, even though
+    Salt users who are not enabling ``gitfs`` will see the bug.
+
+Functional Areas
+^^^^^^^^^^^^^^^^
+
+All bugs should receive a "Functional Area" label to indicate what region of Salt the bug is mainly seen in. This will
+help internal developers as well as community members identify areas of expertise to getting bugs fixed.
+
+Functional Area Labels, in alphabetical order, include:
+
+* Core
+* Documentation
+* Execution Module
+* File Servers
+* Multi-Master
+* Packaging
+* Pillar
+* Platform Mgmt.
+* RAET
+* Returners
+* Salt-API
+* Salt-Cloud
+* Salt-SSH
+* Salt-Syndic
+* State Module
+* Windows
+* ZMQ
+
+Bug Status Labels
+^^^^^^^^^^^^^^^^^
+
+Status lables are used to define and track the state a bug is in at any given time. Not all bugs will have a status
+label, but if a SaltStack employee is able to apply a status label, he or she will. Status labels are somewhat unique
+in the fact that they might be the only label on an issue, such as ``Pending Discussion``, ``Info Needed``, or
+``Expected Behavior`` until further action can be taken.
+
+Cannot Reproduce
+    Someone from the SaltStack team has tried to reproduce the bug with the given information but they are unable to
+    replicate the problem. More information will need to be provided from the original issue-filer before proceeding.
+
+Confirmed
+    A SaltStack engineer has confirmed the reported bug and provided a simple way to reproduce the failure.
+
+Duplicate
+    The issue has been reported already in another report. A link to the other bug report must be provided. At that
+    point the new issue can be closed. Usually, the earliest bug on file is kept as that typically has the most
+    discussion revolving around the issue, though not always. (This can be a "stand-alone" label.)
+
+Expected Behavior
+    The issue reported is expected behavior and nothing needs to be fixed. (This can be a "stand-alone" label.)
+
+Fixed Pending Verification
+    The bug has been fixed and a link to the applicable pull request(s) has been provided, but confirmation is being
+    sought from the community member(s) involved in the bug to test and confirm the fix.
+
+Info Needed
+    More information about the issue is needed before proceeding such as a versions report, a sample state, the command
+    the user was running, or the operating system the error was occurring on, etc. (This can be a "stand-alone" label.)
+
+Upstream Bug
+    The reported bug is something that cannot be fixed in the Salt code base but is instead a bug in another library
+    such a bug in ZMQ or Python. When an issue is labeled with ``Upstream Bug`` then a bug report in the upstream
+    project must be filed (or found if a report already exists) and a link to the report must be provided to the issue
+    in Salt for tracking purposes. (This can be a stand-alone label.)
+
+Won't Fix for Now
+    The SaltStack team has acknowledged the issue at hand is legitimate, but made the call that it’s not something
+    they’re able or willing to fix at this time. These issues may be revisited in the future.
+
+Other
+~~~~~
+
+There are a couple of other labels that are helpful in categorizing bugs that are not included in the categories above.
+These labels can either stand on their own such as ``Question`` or can be applied to bugs or feature requests as
+applicable.
+
+Low Hanging Fruit
+    Applied to bugs that should be easy to fix. This is useful for new contributors to know where some simple things
+    are to get involved in contributing to salt.
+
+Question
+    Used when the issue isn’t a bug nor a feature, but the user has a question about expected behavior, how something
+    works, is misunderstanding a concept, etc. This label is typically applied on its own with ``Blocked`` milestone.
+
+Regression
+    Helps with additional filtering for bug fixing. If something previously worked and now does not work, as opposed to
+    something that never worked in the first place, the issue should be treated with greater urgency.
+
+ZD
+    Stands for “Zen Desk” and is used to help track bugs that customers are seeing as well. Bugs with this label should
+    be treated with greater urgency.
+
+Pull Request Labels
+-------------------
+
+
+Labels that Bridge Issues and Pull Requests
+===========================================
+
+Needs Testcase
+    Used by SaltStack's QA team to realize where pain points are and to bring special attention to where some test
+    coverage needs to occur, especially in areas that have regressed. This label can apply to issues or pull requests,
+    which can also be open or closed. Once tests are written, the pull request containing the tests should be linked to
+    the issue or pull request that originally had the ``Needs Testcase`` label. At this point, the ``Needs Testcase``
+    label must be removed to indicate that tests no longer need to be written.
+
+Pending Discussion
+    If this label is applied to an issue, the issue may or may not be a bug. Enough information was provided about the
+    issue, but some other opinions on the issue are desirable before proceeding. (This can be a "stand-alone" label.)
+    If the label is applied to a pull request, this is used to signal that further discussion must occur before a
+    decision is made to either merge the pull request into the code base or to close it all together.