Merge pull request desktop#4074 from desktop/this-is-how-we-do-it

Update releasing-updates.md instructions

docs/process/releasing-updates.md

@@ -6,25 +6,74 @@ We have three channels to which we can release: `production`, `beta`, and `test`
 
 - `production` is the channel from which the general public downloads and receives updates. It should be stable and polished.
 
-- `beta` is released more often than `production`. It may be buggy and unpolished.
+- `beta` is released more often than `production`. We want to ensure `master` is always in a state where it can be released to users, so it should be used as the source for `beta` releases as an opportunity for additional QA before releasing to `production`.
 
 - `test` is unlike the other two. It does not receive updates. Each test release is locked in time. It's used entirely for providing test releases.
 
 ## The Process
 
-From a clean working directory, set the `GITHUB_ACCESS_TOKEN` environment variable to a valid [Personal Access Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) and run:
+### 1. GitHub Access Token
+
+From a clean working directory, set the `GITHUB_ACCESS_TOKEN` environment variable to a valid [Personal Access Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) 
+
+To check that this environment variable is set in your shell:
+
+**Bash (macOS, Linux or Git Bash)**
+```shellsession
+$ echo $GITHUB_ACCESS_TOKEN
+```
+
+**Command Prompt**
+```shellsession
+$ echo %GITHUB_ACCESS_TOKEN%
+```
+
+**PowerShell**
+```shellsession
+$ echo $env:GITHUB_ACCESS_TOKEN
+```
+
+If you are creating a new Personal Access Token on GitHub:
+* make the token memorable - use a description like `Desktop Draft Release and Changelog Generator`
+* the `read:org` scope is the **only** required scope for drafting releases
+
+To set this access token as an environment in your shell: 
+
+**Bash (macOS, Linux or Git Bash)**
+```shellsession
+$ export GITHUB_ACCESS_TOKEN={your token here}
+```
+
+**Command Prompt**
+```shellsession
+$ set GITHUB_ACCESS_TOKEN={your token here}
+```
+
+**PowerShell**
+```shellsession
+$ $env:GITHUB_ACCESS_TOKEN="{your token here}"
+```
+
+### 2. Create Draft Release
+
+Once the personal access token is set, run the script below, which will determine the next version from what was previously published, based on the desired channel.
+
+For `production` and `beta` releases, run:
 
 ```shellsession
 $ yarn draft-release (production|beta)
 ```
 
-This command will then explain the next steps:
+(For `test` releases, follow the directions in the steps below to update `app/package.json`'s `version` to a higher version and add a changelog entry. The script does not support test yet.)
+
+The script will output a draft changelog, which covers everything that's been merged, and probably needs some love.
+The output will then explain the next steps:
 
 ```shellsession
 Here's what you should do next:
 
-1. Ensure the app/package.json 'version' is set to '1.0.14-beta2'
-2. Add this to changelog.json as a starting point:
+1. Update the app/package.json 'version' to '1.0.14-beta2' (make sure this aligns with semver format of 'major.minor.patch')
+2. Concatenate this to the beginning of the releases element in the changelog.json as a starting point:
 {
   "1.0.14-beta2": [
     "[???] Add RubyMine support for macOS - #3883. Thanks @gssbzn!",
@@ -39,28 +88,22 @@ Here's what you should do next:
   ]
 }
 
-3. Update the release notes so they make sense and only contain user-facing changes
-4. Commit the changes and push them to GitHub
-5. Read this to perform the release: https://github.com/desktop/desktop/blob/master/docs/process/releasing-updates.md
+3. Remove any entries of contributions that don't affect the end user
+3. Update the release notes to have user-friendly summary lines
+4. For issues prefixed with [???], look at the PR and update the prefix to one of: [New], [Added], [Fixed], [Improved], [Removed]
+5. Sort the entries so that the prefixes are ordered: [New], [Added], [Fixed], [Improved], [Removed]
+6. Commit the changes (on master or as new branch) and push them to GitHub
+7. Read this to perform the release: https://github.com/desktop/desktop/blob/master/docs/process/releasing-updates.md
 ```
 
-To walk through this:
+** Note: You should ensure the `version` in `app/package.json` is set to the new version and follows the [semver format](https://semver.org/) of `major.minor.patch`. 
 
- - the script works out the next version from what was previously published, based on the channel
- - you should ensure the `version` in `app/package.json` is set to the new version and follows the [semver format](https://semver.org/) of `major.minor.patch`. Examples:
-    - for prod, `1.1.0` -> `1.1.1` or `1.1.13` -> `1.2.0` 
-    - for beta, `1.1.0-beta1` -> `1.1.0-beta2` or `1.1.13-beta3` -> `1.2.0-beta1`
-    - for test, `1.0.14-test2` -> `1.0.14-test3` or `1.1.14-test3` -> `1.2.0-test1`
- - then, take the draft changelog generated by the script and add it to the `releases` element in `changelog.json`
+Examples:
+* for prod, `1.1.0` -> `1.1.1` or `1.1.13` -> `1.2.0` 
+* for beta, `1.1.0-beta1` -> `1.1.0-beta2` or `1.1.13-beta3` -> `1.2.0-beta1`
+* for test, `1.0.14-test2` -> `1.0.14-test3` or `1.1.14-test3` -> `1.2.0-test1`
 
-The draft changelog covers everything that's been merged, and probably need some love. It's your job from here to:
-
- - remove any entries of contributions that don't affect the end user
- - for issues prefixed with `[???]`, look at the linked PR or issue and change the prefix to one of `[New]`, `[Fixed]`, `[Improved]`, `[Added]` or `[Removed]` based on what best represents the change
- - edit the remaining entries so they make sense
- - sort the entries so that the prefixes are ordered in this way: `[New]`, `[Fixed]`, `[Improved]`, `[Added]`, `[Removed]`
-
-Here's an example of the previous changelog draft afterit has been edited:
+Here's an example of the previous changelog draft after it has been edited:
 
 ```json
 {
@@ -75,18 +118,54 @@ Here's an example of the previous changelog draft afterit has been edited:
 }
 ```
 
-Once you are happy with those changes, commit and push them to GitHub. Get the others on the team to :thumbsup: them if you're not sure.
+Once you've pushed up the version update and the changelog changes, you're ready to release! Get the others on the team to :thumbsup: in a PR if you're not sure. Note that any version change that does not have an associated changelog entry will not successfully release.
+
+### 3. Releasing
 
 When you feel ready to start the deployment, run this command in Chat:
 
 ```
 .release! desktop/YOUR_BRANCH to {production|beta|test}
 ```
 
+If you are releasing from master, YOUR_BRANCH is unnecessary; write:
+```
+.release! desktop to {production|beta|test}
+``` 
+
 We're using `.release` with a bang so that we don't have to wait for any current CI on the branch to finish. This might feel a little wrong, but it's OK since making the release itself will also run CI.
 
-If you're releasing a production update, release a beta update for the next version too, so that beta users are on the latest release.
+If you're releasing a `production` update, release a `beta` update for the next version too, so that beta users are on the latest release.
+
+### 4. Check for Completed Release
+
+Go to [Central's Deployments](https://central.github.com/deployments) to find your release; you'll see something at the top of the page like:
+```
+desktop/desktop deployed from {YOUR_BRANCH}@{HASH_ABBREVIATION_FOR_COMMIT} to {production|beta|test}
+```
+it will initially specify its state as `State: pending` and will be completed when it says `State: released`
+
+You will also see this in Chat:
+`desktopbot tagged desktop/release-{YOUR_VERSION}`
+
+### 5. Test that your app auto-updates to new version
+
+When the release in Central is in `State: released` for `beta` or `production`, switch to your installed Desktop instance and make sure that the corresponding (prod|beta) app auto-updates.
+
+Testing that an update is detected, downloaded, and applied correctly is very important - if this is somehow broken during development then our users will not likely stay up to date!  
+
+If you don't have the app for `beta`, for example, you can always download the previous version on Central to see it update 
+
+** Make sure you move your application out of the Downloads folder and into the Applications folder for macOS or it won't auto-update.
+
+### 6. Check Error Reporting
+
+If an error occurs during the release process, a needle will be reported to Central's [Haystack](https://haystack.githubapp.com/central).
+
+It is normal to monitor Haystack closely for 15 minutes just to make sure.
+
+### 6. Celebrate
 
-## Error Reporting
+Once your app updates and you see the visible changes in your app and there are no spikes in errors, celebrate 🎉!!! You did it!
 
-If an error occurs during the release process, a needle will be reported to Central's [haystack](https://haystack.githubapp.com/central).
+Also it might make sense to continue to monitor Haystack in the background for the next 24 hours.

script/draft-release/run.ts

@@ -47,12 +47,15 @@ function printInstructions(nextVersion: string, entries: Array<string>) {
   object[`${nextVersion}`] = entries.sort()
 
   const steps = [
-    `Ensure the app/package.json 'version' is set to '${nextVersion}'`,
-    `Add this to changelog.json as a starting point:\n${jsonStringify(
+    `Update the app/package.json 'version' to '${nextVersion}' (make sure this aligns with semver format of 'major.minor.patch')`,
+    `Concatenate this to the beginning of the 'releases' element in the changelog.json as a starting point:\n${jsonStringify(
       object
     )}\n`,
-    'Update the release notes so they make sense and only contain user-facing changes',
-    'Commit the changes and push them to GitHub',
+    `Remove any entries of contributions that don't affect the end user`,
+    'Update the release notes to have user-friendly summary lines',
+    'For issues prefixed with [???], look at the PR to update the prefix to one of: [New], [Added], [Fixed], [Improved], [Removed]',
+    'Sort the entries so that the prefixes are ordered in this way: [New], [Added], [Fixed], [Improved], [Removed]',
+    'Commit the changes (on master or as new branch) and push them to GitHub',
     'Read this to perform the release: https://github.com/desktop/desktop/blob/master/docs/process/releasing-updates.md',
   ]