Doc updates, remove PR template, update issue labels (PowerShell#1776)

lzybkr · mirichmo · commit 110c627be8f7 · 2016-08-12T18:19:12.000-07:00
* Remove PR template, update guidelines for PR

* Update testing-guidelines.md

* Add clarification on when to use runtime/compiletime checks

* Update issue label descriptions
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -34,7 +34,7 @@ Contributing to Issues
 * If you can't find your issue already,
   [open a new issue](https://github.com/PowerShell/PowerShell/issues/new),
   making sure to follow the directions as best you can.
-* If the issue is marked as [`help wanted`][help-wanted-issue],
+* If the issue is marked as [`0 - Backlog`][help-wanted-issue],
   the PowerShell maintainers are looking for help with the issue.
 
 Contributing to Documentation
@@ -80,6 +80,16 @@ Additional references:
 
 ### Lifecycle of a pull request
 
+#### Before submitting
+
+* To avoid merge conflicts, make sure your branch is rebased on the `master` branch of this repository.
+* Many code changes will require new tests,
+  so make sure you've added a new test if existing tests do not effectively test the code changed.
+* Clean up your commit history.
+  Each commit should be a **single complete** change.
+  This discipline is important when reviewing the changes as well as when using `git bisect` and `git revert`.
+
+
 #### Pull request submission
 
 **Always create a pull request to the `master` branch of this repository**.
@@ -94,13 +104,14 @@ See [Contributing to documentation related to PowerShell](#contributing-to-docum
   A better example is: "Add Ensure parameter to New-Item cmdlet", with "Fixes #5" in the PR's body.
 
 * When you create a pull request,
-  fill out the pull request template,
-  including a summary of what's included in your changes.
-  If the changes are related to an existing GitHub issue,
+  including a summary of what's included in your changes and
+  if the changes are related to an existing GitHub issue,
   please reference the issue in pull request description (e.g. ```Closes #11```).
   See [this][closing-via-message] for more details.
 
-* Include an update to the [changelog](../CHANGELOG.MD) in your pull request.
+* If the change warrants a note in the [changelog](../CHANGELOG.MD)
+  either update the changelog in your pull request or
+  add a comment in the PR description saying that the change may warrant a note in the changelog.
   New changes always go into the **Unreleased** section.
   Keeping the changelog up-to-date simplifies the release process for maintainers.
   An example:
@@ -260,5 +271,5 @@ Once you sign a CLA, all your existing and future pull requests will be labeled
 [good-git-resources]: https://help.github.com/articles/good-resources-for-learning-git-and-github/
 [contribute-issues]: #contributing-to-issues
 [open-issue]: https://github.com/PowerShell/PowerShell/issues
-[help-wanted-issue]: https://github.com/PowerShell/PowerShell/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22
+[help-wanted-issue]: https://github.com/PowerShell/PowerShell/issues?q=is%3Aopen+is%3Aissue+label%3A%220%20-%20Backlog%22
 [semantic linefeeds]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
diff --git a/docs/dev-process/coding-guidelines.md b/docs/dev-process/coding-guidelines.md
@@ -78,4 +78,7 @@ When absolutely necessary, avoid duplicating more code than necessary,
 and instead prefer introducing helper functions to minimize the platform differences.
 
 When adding platform dependent code, prefer preprocessor directives
-over runtime checks.  
+over runtime checks.
+
+We produce a single binary for all UNIX variants,
+so runtime checks are currently necessary for some platform differences, e.g. OS X and Linux.
diff --git a/docs/maintainers/issue-management.md b/docs/maintainers/issue-management.md
@@ -1,26 +1,54 @@
 # Issue Management
 
 ## Long-living issue labels
+=======
+## Issue and PR Labels
+
+Issues are opened for many different reasons.
+We use the following labels for issue classifications:
+
+* `Issue-Bug`: the issue is reporting a bug
+* `Issue-Discussion`: the issue may not have a clear classification yet.
+  The issue may generate a [RFC][ln-rfc] or maybe be reclassified as a bug or enhancement.
+* `Issue-Enhancment`: the issue is more of a feature request than a bug.
+* `Issue-Meta`: an issue used to track multiple issues
+* `Issue-Question`: ideally support can be provided via other mechanisms,
+  but sometimes folks to open an issue to get a question answered and we will use this label for such issues.
+
+[ln-rfc]: https://github.com/PowerShell/PowerShell-RFC
+
+When an issue is resolved, the following labels are used to describe the resolution:
+
+* `Resolution-Answered`: the issue was a `Issue-Question` and was answered.
+* `Resolution-By Design`: the issue is not considered a bug, the behavior is working as designed
+* `Resolution-Duplicate`: the issue is a duplicate - there must be a comment linking to another issue
+* `Resolution-Fixed`: the issue is has been fixed and should be referenced from a PR
+* `Resolution-Won't Fix`: the issue may be considered a bug or enhancement but won't be fixed.
+  If there is an inadequate explanation as to why the issue was closed,
+  anyone should feel free to reopen the issue.
 
 ### Feature areas
 
-These labels describe what feature area of PowerShell that an issue addresses.
+These labels describe what feature area of PowerShell that an issue affects.
 
 * `Area-Build`: build issues
 * `Area-Cmdlets`: cmdlets in any module
 * `Area-Console`: the console experience
 * `Area-Debugging`: debugging PowerShell script
+* `Area-Demo`: a demo or sample
 * `Area-Documentation`: PowerShell *repo* documentation issues, general PowerShell doc issues go [here](https://github.com/PowerShell/PowerShell-Docs/issues)
 * `Area-Engine`: core PowerShell engine, interpreter, runtime
+* `Area-HelpSystem`: anything related to the help infrastructure and formatting of help
 * `Area-Intellisense`: tab completion
 * `Area-Language`: parser, language semantics
 * `Area-OMI`: omi
 * `Area-PackageManagement`: PackageManagement related issues
 * `Area-Performance`: a performance issue
 * `Area-Portability`: anything affecting script portability
-* `Area-PSReadline`: PSReadLine
-* `Area-SideBySide`: Side by side support
-* `Area-Test`: tests or test infrastructure
+* `Area-PowerShellGet`: PowerShellGet related issues
+* `Area-PSReadline`: PSReadLine related issues
+* `Area-SideBySide`: side by side support
+* `Area-Test`:issues in a test or in test infrastructure
 
 ### Operating systems
 
@@ -33,14 +61,25 @@ These are for issues that are specific to certain operating systems:
 
 Issues can be in one of the following states:
 * `0 - Backlog` : We've acknowledged the issue but have no immediate plans to address it.
+  If you're looking for a way to contribute, these issues can be a good place to start.
 * `1 - Planning` : The issue requires some design or discussion before coding can begin.
 * `2 - Ready` : Any design or discussion is essentially done, coding has not yet begun though.
 * `3 - Working` : The assignee(s) are actively working on the issue.
 * `4 - In Review` : The issue is being reviewed.
-The assignee(s) are responsible for signing off before the PR will be merged.
+  The assignee(s) are responsible for signing off before the PR will be merged.
+
+The following labels are used on PRs:
+
+* `Review - Needed` : The PR is being reviewed.  Please see [Pull Request - Code Review](../../.github/CONTRIBUTING.md#pull-request-code-review)
+* `Review - Waiting on Author` : The PR was reviewed by the team and requires changes or comments from the author before being accepted.
+
+### Random labels
 
-* `help wanted` : We are looking for someone to work on this issue.
-* `need review` : This pull request is being reviewed.  Please see [Pull Request - Code Review](../../.github/CONTRIBUTING.md#pull-request-code-review)
-* `waiting for author`: The issue or pull request needs 
-* `add to changelog`: The PR requires an addition to the changelog. 
-Should be removed when it has been added. 
+* `Blocked`: an issue cannot be addressed due to external factors,
+  but should not be closed because those external factors are temporary.
+* `BVT/DRT`: an issue affecting or exposed by tests that have not been open sourced.
+* `Porting`: an issue that affects a feature not yet ported to other platforms.
+* `Usability`: this label is used to help us filter issues that might be higher priority
+  because they more directly affect the usability of a particular feature or area.
+* `Changelog Needed`: The PR requires an addition to the changelog,
+  and should be removed when it has been added.
diff --git a/docs/testing-guidelines/testing-guidelines.md b/docs/testing-guidelines/testing-guidelines.md
@@ -1,9 +1,9 @@
 
 # Testing Guidelines
 
-Testing is a critical part of the PowerShell project. 
+Testing is a critical and required part of the PowerShell project.
 
-The PowerShell team created nearly 100,000 tests over the last 12 years which we run as part of the release process for Windows PowerShell.
+The Microsoft PowerShell team created nearly 100,000 tests over the last 12 years which we run as part of the release process for Windows PowerShell.
 Having all of those tests available for the initial release of PowerShell was not feasible, and we have targeted those tests which
 we believe will provide us the ability to catch regressions in the areas which have had the largest changes for PowerShell. 
 It is our intent to continue to release more and more of our tests until we have the coverage we need.
