Merge pull request #2186 from cli/help-wanted-docs

Improve contributing documentation

.github/CONTRIBUTING.md

@@ -1,11 +1,5 @@
 ## Contributing
 
-[legal]: https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license
-[license]: ../LICENSE
-[code-of-conduct]: CODE-OF-CONDUCT.md
-[bug issues]: https://github.com/cli/cli/issues?q=is%3Aopen+is%3Aissue+label%3Abug
-[feature request issues]: https://github.com/cli/cli/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement
-
 Hi! Thanks for your interest in contributing to the GitHub CLI!
 
 We accept pull requests for bug fixes and features where we've discussed the approach in an issue and given the go-ahead for a community member to work on it. We'd also love to hear about ideas for new features as issues.
@@ -17,11 +11,11 @@ Please do:
 * Open an issue to propose a significant change.
 * Open a pull request to fix a bug.
 * Open a pull request to fix documentation about a command.
-* Open a pull request for an issue with the `help-wanted` label and leave a comment claiming it.
+* Open a pull request for any issue labelled [`help wanted`][hw] or [`good first issue`][gfi].
 
 Please avoid:
 
-* Opening pull requests for issues marked `needs-design`, `needs-investigation`, `needs-user-input`, or `blocked`.
+* Opening pull requests for issues marked `needs-design`, `needs-investigation`, or `blocked`.
 * Adding installation instructions specifically for your OS/package manager.
 * Opening pull requests for any issue marked `core`. These issues require additional context from
   the core CLI team at GitHub and any external pull requests will not be accepted.
@@ -52,6 +46,18 @@ We generate manual pages from source on every release. You do not need to submit
 
 ## Resources
 
-- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
-- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
-- [GitHub Help](https://help.github.com)
+- [How to Contribute to Open Source][]
+- [Using Pull Requests][]
+- [GitHub Help][]
+
+
+[bug issues]: https://github.com/cli/cli/issues?q=is%3Aopen+is%3Aissue+label%3Abug
+[feature request issues]: https://github.com/cli/cli/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement
+[hw]: https://github.com/cli/cli/labels/help%20wanted
+[gfi]: https://github.com/cli/cli/labels/good%20first%20issue
+[legal]: https://docs.github.com/en/free-pro-team@latest/github/site-policy/github-terms-of-service#6-contributions-under-repository-license
+[license]: ../LICENSE
+[code-of-conduct]: ./CODE-OF-CONDUCT.md
+[How to Contribute to Open Source]: https://opensource.guide/how-to-contribute/
+[Using Pull Requests]: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests
+[GitHub Help]: https://docs.github.com/

README.md

@@ -4,17 +4,16 @@
 
 ![screenshot of gh pr status](https://user-images.githubusercontent.com/98482/84171218-327e7a80-aa40-11ea-8cd1-5177fc2d0e72.png)
 
-## Availability
-
 GitHub CLI is available for repositories hosted on GitHub.com and GitHub Enterprise Server 2.20+, and to install on macOS, Windows, and Linux.
 
 ## Documentation
 
-Read the [official docs][] for usage and more information.
+[See the manual][manual] for setup and usage instructions.
 
-## We want your feedback
+## Contributing
+
+If anything feels off, or if you feel that some functionality is missing, please check out the [contributing page][contributing]. There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.
 
-We'd love to hear your feedback about `gh`. If you spot bugs or have features that you'd really like to see in `gh`, please check out the [contributing page][].
 
 <!-- this anchor is linked to from elsewhere, so avoid renaming it -->
 ## Installation
@@ -86,13 +85,13 @@ tools bring GitHub to the terminal, `hub` behaves as a proxy to `git`, and `gh`
 tool. Check out our [more detailed explanation][gh-vs-hub] to learn more.
 
 
-[official docs]: https://cli.github.com/manual
+[manual]: https://cli.github.com/manual/
 [Homebrew]: https://brew.sh
 [MacPorts]: https://www.macports.org
 [scoop]: https://scoop.sh
 [Chocolatey]: https://chocolatey.org
 [releases page]: https://github.com/cli/cli/releases/latest
 [hub]: https://github.com/github/hub
-[contributing page]: https://github.com/cli/cli/blob/trunk/.github/CONTRIBUTING.md
+[contributing]: ./.github/CONTRIBUTING.md
 [gh-vs-hub]: ./docs/gh-vs-hub.md
 [build from source]: ./docs/source.md

docs/triage.md

@@ -16,51 +16,40 @@ triage day.
 
 # Incoming issues
 
-just imagine a flowchart
-
 - can this be closed outright?
   - e.g. spam/junk
   - close without comment
 - do we not want to do it?
   - e.g. have already discussed not wanting to do or duplicate issue
-  - comment acknowledging receipt
-  - close
+  - comment and close
 - do we want someone in the community to do it?
   - e.g. the task is relatively straightforward, but no people on our team have the bandwidth to take it on at the moment
   - ensure that the thread contains all the context necessary for someone new to pick this up
-  - add `help-wanted` label
-- do we want to do it, but not in the next year?
-  - comment acknowledging it, but that we don't plan on working on it this year.
-  - add `future` label
-  - add additional labels as needed(examples include `enhancement` or `bug`)
-  - close
+  - add `help wanted` label
+  - consider adding `good first issue` label
 - do we want to do it?
-  - e.g. bugs or things we have discussed before
   - comment acknowledging it
   - label appropriately
-  - add to project TODO column if appropriate, otherwise just leave it labeled
-- is it intriguing but needs discussion?
+  - add to project TODO column if this is something that should ship soon
+- is it intriguing, but requires discussion?
   - label `needs-design` if design input is needed, ping
   - label `needs-investigation` if engineering research is required before action can be taken
-  - ping engineers if eng needed
-  - ping product if it's about future directions/roadmap/big changes
 - does it need more info from the issue author?
-  - ask the user for that
+  - ask the user for details
   - add `needs-user-input` label
-- is it a user asking for help and you have all the info you need to help?
-  - try and help
+- is it a usage/support question?
+  - offer some instructions/workaround and close
 
 # Incoming PRs
 
 just imagine a flowchart
 
 - can it be closed outright?
-  - ie spam/junk
-- do we not want to do it?
-  - ie have already discussed not wanting to do, duplicate issue
-  - comment acknowledging receipt
+  - e.g. spam/junk
   - close
-- is it intriguing but needs discussion?
+- do we not want to do it?
+  - comment and close
+- is it intriguing, but requires discussion and there is no referenced issue?
   - request an issue
   - close
 - is it something we want to include?
@@ -82,7 +71,7 @@ For each PR, ask:
 
 ## Examples
 
-We want the cli/cli repo to be a safe and encouraging open-source environment. Below are some examples
+We want our project to be a safe and encouraging open-source environment. Below are some examples
 of how to empathetically respond to or close an issue/PR:
 
 - [Closing a quality PR its scope is too large](https://github.com/cli/cli/pull/1161)