diff --git a/RELEASING.md b/RELEASING.md index 04e11984..ead6293a 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -7,64 +7,79 @@ Releasing a new version of the `git` gem requires these steps: -- [How to release a new git.gem](#how-to-release-a-new-gitgem) - - [Install Prerequisites](#install-prerequisites) - - [Prepare the Release](#prepare-the-release) - - [Review and Merge the Release](#review-and-merge-the-release) - - [Build and Release the Gem](#build-and-release-the-gem) - -These instructions use an example where: - -- The default branch is `master` -- The current release version is `1.5.0` -- You want to create a new *minor* release, `1.6.0` +* [Install Prerequisites](#install-prerequisites) +* [Determine the SemVer release type](#determine-the-semver-release-type) +* [Create the release](#create-the-release) +* [Review the CHANGELOG and release PR](#review-the-changelog-and-release-pr) +* [Manually merge the release PR](#manually-merge-the-release-pr) +* [Publish the git gem to RubyGems.org](#publish-the-git-gem-to-rubygemsorg) ## Install Prerequisites The following tools need to be installed in order to create the release: -- [git](https://git-scm.com) is used to interact with the local and remote repositories -- [gh](https://cli.github.com) is used to create the release and PR in GitHub -- [Docker](https://www.docker.com) is used to run the script to create the release notes +* [create_githhub_release](https://github.com/main-branch/create_github_release) is used to create the release +* [git](https://git-scm.com) is used by `create-github-release` to interact with the local and remote repositories +* [gh](https://cli.github.com) is used by `create-github-release` to create the release and PR in GitHub -On a Mac, these tools can be installed using [brew](https://brew.sh): +On a Mac, these tools can be installed using [gem](https://guides.rubygems.org/rubygems-basics/) and [brew](https://brew.sh): ```shell +$ gem install create_github_release +... $ brew install git ... $ brew install gh ... -$ brew install --cask docker -... $ ``` -## Prepare the Release +## Determine the SemVer release type -Bump the version, create release notes, tag the release and create a GitHub release and PR which can be used to review the release. +Determine the SemVer version increment that should be applied for the new release: -Steps: +* `major`: when the release includes incompatible API or functional changes. +* `minor`: when the release adds functionality in a backward-compatible manner +* `patch`: when the release includes small user-facing changes that are + backward-compatible and do not introduce new functionality. -- Check out the code with `git clone https://github.com/ruby-git/ruby-git ruby-git-v1.6.0 && cd ruby-git-v1.6.0` -- Install development dependencies using bundle `bundle install` -- Based upon the nature of the changes, decide on the type of release: `major`, `minor`, or `patch` (in this example we will use `minor`) -- Run the release script `bundle exec create-github-release minor` +## Create the release -## Review and Merge the Release +Create the release using the `create-github-release` command. If the release type +is `major`, the command is: -Have the release PR approved and merge the changes into the `master` branch. +```shell +create-github-release major +``` -**IMPORTANT** DO NOT merge to the `master` branch using the GitHub UI. Instead use the instructions below. +Follow the directions given by the `create-github-release` command to finish the +release. Where the instructions given by the command differ than the instructions +below, follow the instructions given by the command. -Steps: +## Review the CHANGELOG and release PR -- Get the release PR reviewed and approved in GitHub -- Merge the changes with the command `git checkout master && git merge --ff-only v1.6.0 && git push` +The `create-github-release` command will output a link to the CHANGELOG and the PR +it created for the release. Review the CHANGELOG and have someone review and approve +the release PR. -## Build and Release the Gem +## Manually merge the release PR -Build the gem and publish it to [rubygems.org](https://rubygems.org/gems/git) +It is important to manually merge the PR so a separate merge commit can be avoided. +Use the commands output by the `create-github-release` which will looks like this +if you are creating a 2.0.0 release: -Steps: +```shell +git checkout master +git merge --ff-only release-v2.0.0 +git push +``` + +This will automatically close the release PR. + +## Publish the git gem to RubyGems.org -- Build and release the gem using rake `bundle exec rake release` +Finally, publish the git gem to RubyGems.org using the following command: + +```shell +rake release:rubygem_push +```