|
7 | 7 |
|
8 | 8 | Releasing a new version of the `git` gem requires these steps: |
9 | 9 |
|
10 | | -- [How to release a new git.gem](#how-to-release-a-new-gitgem) |
11 | | - - [Install Prerequisites](#install-prerequisites) |
12 | | - - [Prepare the Release](#prepare-the-release) |
13 | | - - [Review and Merge the Release](#review-and-merge-the-release) |
14 | | - - [Build and Release the Gem](#build-and-release-the-gem) |
15 | | - |
16 | | -These instructions use an example where: |
17 | | - |
18 | | -- The default branch is `master` |
19 | | -- The current release version is `1.5.0` |
20 | | -- You want to create a new *minor* release, `1.6.0` |
| 10 | +* [Install Prerequisites](#install-prerequisites) |
| 11 | +* [Determine the SemVer release type](#determine-the-semver-release-type) |
| 12 | +* [Create the release](#create-the-release) |
| 13 | +* [Review the CHANGELOG and release PR](#review-the-changelog-and-release-pr) |
| 14 | +* [Manually merge the release PR](#manually-merge-the-release-pr) |
| 15 | +* [Publish the git gem to RubyGems.org](#publish-the-git-gem-to-rubygemsorg) |
21 | 16 |
|
22 | 17 | ## Install Prerequisites |
23 | 18 |
|
24 | 19 | The following tools need to be installed in order to create the release: |
25 | 20 |
|
26 | | -- [git](https://git-scm.com) is used to interact with the local and remote repositories |
27 | | -- [gh](https://cli.github.com) is used to create the release and PR in GitHub |
28 | | -- [Docker](https://www.docker.com) is used to run the script to create the release notes |
| 21 | +* [create_githhub_release](https://github.com/main-branch/create_github_release) is used to create the release |
| 22 | +* [git](https://git-scm.com) is used by `create-github-release` to interact with the local and remote repositories |
| 23 | +* [gh](https://cli.github.com) is used by `create-github-release` to create the release and PR in GitHub |
29 | 24 |
|
30 | | -On a Mac, these tools can be installed using [brew](https://brew.sh): |
| 25 | +On a Mac, these tools can be installed using [gem](https://guides.rubygems.org/rubygems-basics/) and [brew](https://brew.sh): |
31 | 26 |
|
32 | 27 | ```shell |
| 28 | +$ gem install create_github_release |
| 29 | +... |
33 | 30 | $ brew install git |
34 | 31 | ... |
35 | 32 | $ brew install gh |
36 | 33 | ... |
37 | | -$ brew install --cask docker |
38 | | -... |
39 | 34 | $ |
40 | 35 | ``` |
41 | 36 |
|
42 | | -## Prepare the Release |
| 37 | +## Determine the SemVer release type |
43 | 38 |
|
44 | | -Bump the version, create release notes, tag the release and create a GitHub release and PR which can be used to review the release. |
| 39 | +Determine the SemVer version increment that should be applied for the new release: |
45 | 40 |
|
46 | | -Steps: |
| 41 | +* `major`: when the release includes incompatible API or functional changes. |
| 42 | +* `minor`: when the release adds functionality in a backward-compatible manner |
| 43 | +* `patch`: when the release includes small user-facing changes that are |
| 44 | + backward-compatible and do not introduce new functionality. |
47 | 45 |
|
48 | | -- 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` |
49 | | -- Install development dependencies using bundle `bundle install` |
50 | | -- Based upon the nature of the changes, decide on the type of release: `major`, `minor`, or `patch` (in this example we will use `minor`) |
51 | | -- Run the release script `bundle exec create-github-release minor` |
| 46 | +## Create the release |
52 | 47 |
|
53 | | -## Review and Merge the Release |
| 48 | +Create the release using the `create-github-release` command. If the release type |
| 49 | +is `major`, the command is: |
54 | 50 |
|
55 | | -Have the release PR approved and merge the changes into the `master` branch. |
| 51 | +```shell |
| 52 | +create-github-release major |
| 53 | +``` |
56 | 54 |
|
57 | | -**IMPORTANT** DO NOT merge to the `master` branch using the GitHub UI. Instead use the instructions below. |
| 55 | +Follow the directions given by the `create-github-release` command to finish the |
| 56 | +release. Where the instructions given by the command differ than the instructions |
| 57 | +below, follow the instructions given by the command. |
58 | 58 |
|
59 | | -Steps: |
| 59 | +## Review the CHANGELOG and release PR |
60 | 60 |
|
61 | | -- Get the release PR reviewed and approved in GitHub |
62 | | -- Merge the changes with the command `git checkout master && git merge --ff-only v1.6.0 && git push` |
| 61 | +The `create-github-release` command will output a link to the CHANGELOG and the PR |
| 62 | +it created for the release. Review the CHANGELOG and have someone review and approve |
| 63 | +the release PR. |
63 | 64 |
|
64 | | -## Build and Release the Gem |
| 65 | +## Manually merge the release PR |
65 | 66 |
|
66 | | -Build the gem and publish it to [rubygems.org](https://rubygems.org/gems/git) |
| 67 | +It is important to manually merge the PR so a separate merge commit can be avoided. |
| 68 | +Use the commands output by the `create-github-release` which will looks like this |
| 69 | +if you are creating a 2.0.0 release: |
67 | 70 |
|
68 | | -Steps: |
| 71 | +```shell |
| 72 | +git checkout master |
| 73 | +git merge --ff-only release-v2.0.0 |
| 74 | +git push |
| 75 | +``` |
| 76 | + |
| 77 | +This will automatically close the release PR. |
| 78 | + |
| 79 | +## Publish the git gem to RubyGems.org |
69 | 80 |
|
70 | | -- Build and release the gem using rake `bundle exec rake release` |
| 81 | +Finally, publish the git gem to RubyGems.org using the following command: |
| 82 | + |
| 83 | +```shell |
| 84 | +rake release:rubygem_push |
| 85 | +``` |
0 commit comments