Skip to content

Latest commit

 

History

History
171 lines (120 loc) · 7.21 KB

releasing-updates.md

File metadata and controls

171 lines (120 loc) · 7.21 KB

Releasing Updates

Channels

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. 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

1. GitHub Access Token

From a clean working directory, set the GITHUB_ACCESS_TOKEN environment variable to a valid Personal Access Token

To check that this environment variable is set in your shell:

Bash (macOS, Linux or Git Bash)

$ echo $GITHUB_ACCESS_TOKEN

Command Prompt

$ echo %GITHUB_ACCESS_TOKEN%

PowerShell

$ 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)

$ export GITHUB_ACCESS_TOKEN={your token here}

Command Prompt

$ set GITHUB_ACCESS_TOKEN={your token here}

PowerShell

$ $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:

$ yarn draft-release (production|beta)

(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:

Here's what you should do next:

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!",
    "[???] Allow window to accept single click on focus - #3843",
    "[???] Drop unnecessary comments before issue template - #3906",
    "[???] First-class changelog script for generating release notes - #3888",
    "[???] Fix expanded avatar stack overflow - #3884",
    "[???] Switch to a saner default gravatar size - #3911",
    "[Fixed] Add a repository settings store - #934",
    "[Fixed] Ensure renames are detected when viewing commit diffs - #3673",
    "[Fixed] Line endings are hard, lets go shopping - #3514",
  ]
}

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

** Note: You should ensure the version in app/package.json is set to the new version and follows the semver format 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

Here's an example of the previous changelog draft after it has been edited:

{
  "1.0.14-beta2": [
    "[Added] Add RubyMine support for macOS - #3883. Thanks @gssbzn!",
    "[Fixed] Allow window to accept single click on focus - #3843",
    "[Fixed] Expanded avatar list hidden behind commit details - #3884",
    "[Fixed] Renames not detected when viewing commit diffs - #3673",
    "[Fixed] Ignore action assumes CRLF when core.autocrlf is unset - #3514",
    "[Improved] Use smaller default size when rendering Gravatar avatars - #3911",
  ]
}

Once you've pushed up the version update and the changelog changes, you're ready to release! Get the others on the team to 👍 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.

4. Check for Completed Release

Go to Central's 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.

It is normal to monitor Haystack closely for 15 minutes just to make sure.

6. Celebrate

Once your app updates and you see the visible changes in your app and there are no spikes in errors, celebrate 🎉!!! You did it!

Also it might make sense to continue to monitor Haystack in the background for the next 24 hours.