Merge pull request #1362 from cli/triage-releasing-tweaks

Expand our releasing, triage docs

docs/releasing.md

@@ -1,24 +1,37 @@
 # Releasing
 
-_First create a prerelease to verify the relase infrastructure_
+Our build system automatically compiles and attaches cross-platform binaries to any git tag named `vX.Y.Z`. The automated changelog is generated from commit messages starting with “Merge pull request …” that landed between this tag and the previous one (as determined topologically by git).
 
-1. `git tag v1.2.3-pre`
-2. `git push origin v1.2.3-pre`
-3. Wait several minutes for the build to run <https://github.com/cli/cli/actions>
-4. Verify the prerelease succeeded and has the correct artifacts at <https://github.com/cli/cli/releases>
+Users who run official builds of `gh` on their machines will get notified about the new version within a 24 hour period.
 
-_Next create a the production release_
+To test out the build system, publish a prerelease tag with a name such as `vX.Y.Z-pre.0` or `vX.Y.Z-rc.1`. Note that such a release will still be public, but it will be marked as a "prerelease", meaning that it will never show up as a "latest" release nor trigger upgrade notifications for users.
 
-5. `git tag v1.2.3`
-6. `git push origin v1.2.3`
-7. Wait several minutes for the build to run <https://github.com/cli/cli/actions>
-8. Check <https://github.com/cli/cli/releases>
-9. Verify the marketing site was updated https://cli.github.com/
-10. Delete the prerelease on GitHub <https://github.com/cli/cli/releases>
+## General guidelines
+
+* Features to be released should be reviewed and approved at least one day prior to the release.
+* Feature releases should bump up the minor version number.
+
+## Tagging a new release
+
+1. `git tag v1.2.3 && git push origin v1.2.3`
+2. Wait several minutes for builds to run: <https://github.com/cli/cli/actions>
+3. Check <https://github.com/cli/cli/releases>
+4. Scan generated release notes and optionally add a human touch by grouping items under topic sections
+5. Verify the marketing site was updated: <https://cli.github.com>
+6. (Optional) Delete any pre-releases related to this release.
+
+A successful build will result in changes across several repositories:
+* <https://github.com/github/cli.github.com>
+* <https://github.com/github/homebrew-gh>
+* <https://github.com/Homebrew/homebrew-core/pulls>
+* <https://github.com/cli/scoop-gh>
+
+If the build fails, there is not a clean way to re-run it. The easiest way would be to start over by deleting the partial release on GitHub and re-publishing the tag. Note that this might be disruptive to users or tooling that were already notified about an upgrade. If a functional release and its binaries are already out there, it might be better to try to manually fix up only the specific workflow tasks that failed. Use your best judgement depending on the failure type.
 
 ## Release locally for debugging
 
 A local release can be created for testing without creating anything official on the release page.
 
+0. Make sure GoReleaser is installed: `brew install goreleaser`
 1. `goreleaser --skip-validate --skip-publish --rm-dist`
-2. Check and test files in `dist/`
+2. Find the built products under `dist/`.

docs/triage.md

@@ -25,6 +25,10 @@ just imagine a flowchart
   - e.g. have already discussed not wanting to do or duplicate issue
   - comment acknowledging receipt
   - 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