releasing-updates.md

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. It may be buggy and unpolished.

• 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 and run:

$ yarn draft-release (production|beta)

This command will then explain the next steps:

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

To walk through this:

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

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:

{
  "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 are happy with those changes, commit and push them to GitHub. Get the others on the team to 👍 them if you're not sure.

When you feel ready to start the deployment, run this command in Chat:

.release! desktop/YOUR_BRANCH 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.

Error Reporting

If an error occurs during the release process, a needle will be reported to Central's haystack.