Skip to content

Update release instructions #606

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 12, 2023
Merged

Update release instructions #606

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 60 additions & 58 deletions RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,61 +8,63 @@
Releasing a new version of the `git` gem requires these steps:

- [How to release a new git.gem](#how-to-release-a-new-gitgem)
- [Prepare the release](#prepare-the-release)
- [Create a GitHub release](#create-a-github-release)
- [Build and release the gem](#build-and-release-the-gem)

These instructions use an example where the current release version is `1.5.0`
and the new release version to be created is `1.6.0.pre1`.

## Prepare the release

From a fork of ruby-git, create a PR containing changes to (1) bump the
version number, (2) update the CHANGELOG.md, and (3) tag the release.

- Bump the version number in lib/git/version.rb following [Semantic Versioning](https://semver.org)
guidelines
- Add a link in CHANGELOG.md to the release tag which will be created later
in this guide
- Create a new tag using [git-extras](https://github.com/tj/git-extras/blob/master/Commands.md#git-release)
`git release` command
- For example: `git release v1.6.0.pre1`
- These should be the only changes in the PR
- An example of these changes for `v1.6.0.pre1` can be found in [PR #435](https://github.com/ruby-git/ruby-git/pull/435)
- Get the PR reviewed, approved and merged to master.

## Create a GitHub release

On [the ruby-git releases page](https://github.com/ruby-git/ruby-git/releases),
select `Draft a new release`

- Select the tag corresponding to the version being released `v1.6.0.pre1`
- The Target should be `master`
- For the release description, use the output of [changelog-rs](https://github.com/perlun/changelog-rs)
- A Docker image is provided in [Dockerfile.changelog-rs](https://github.com/ruby-git/ruby-git/blob/master/Dockerfile.changelog-rs)
so you don't have to install changelog-rs or the Rust tool chain. To build the
Docker image, run this command from this project's root directory:
- `docker build --file Dockerfile.changelog-rs --tag changelog-rs .`
- To run the changelog-rs command using this image, run the following command
from this project's root directory (replace the tag names appropriate for the
current release):
- `docker run --rm --volume "$PWD:/worktree" changelog-rs v1.5.0 v1.6.0.pre1`
- Copy the output, omitting the tag header `## v1.6.0.pre1` and paste into
the release description
- The release description can be edited later if needed
- Select the appropriate value for `This is a pre-release`
- Since `v1.6.0.pre1` is a pre-release, check `This is a pre-release`

## Build and release the gem

Clone [ruby-git/ruby-git](https://github.com/ruby-git/ruby-git) directly (not a
fork) and ensure your local working copy is on the master branch

- Verify that you are not on a fork with the command `git remote -v`
- Verify that the version number is correct by running `rake -T` and inspecting
the output for the `release[remote]` task

Build the git gem and push it to rubygems.org with the command `rake release`

- Ensure that your `gem sources list` includes `https://rubygems.org` (in my
case, I usually have my work’s internal gem repository listed)
- [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

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

On a Mac, these tools can be installed using [brew](https://brew.sh):

```shell
$ brew install git
...
$ brew install gh
...
$ brew install --cask docker
...
$
```

## Prepare the Release

Bump the version, create release notes, tag the release and create a GitHub release and PR which can be used to review the release.

Steps:

- 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-realese minor`

## Review and Merge the Release

Have the release PR approved and merge the changes into the `master` branch.

**IMPORTANT** DO NOT merge to the `master` branch using the GitHub UI. Instead use the instructions below.

Steps:

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

## Build and Release the Gem

Build the gem and publish it to [rubygems.org](https://rubygems.org/gems/git)

Steps:

- Build and release the gem using rake `bundle exec rake release`
1 change: 1 addition & 0 deletions git.gemspec
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Gem::Specification.new do |s|
s.add_runtime_dependency 'rchardet', '~> 1.8'

s.add_development_dependency 'bump', '~> 0.10'
s.add_development_dependency 'create_github_release', '~> 0.2'
s.add_development_dependency 'minitar', '~> 0.9'
s.add_development_dependency 'rake', '~> 13.0'
s.add_development_dependency 'test-unit', '~> 3.3'
Expand Down