Skip to content

[docs/releasing.md] Add basic info for homebrew update flow #10344

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
andyfeller merged 3 commits into from
Feb 6, 2025
Merged

[docs/releasing.md] Add basic info for homebrew update flow #10344

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
abe6d8d
[docs/releasing.md] Add basic info for homebrew update flow
iamazeem Jan 31, 2025
0f16c87
Merge branch 'trunk' into 8386-update-release-doc-with-homebrew-info
iamazeem Jan 31, 2025
4cf0901
Update release doc content
andyfeller Feb 6, 2025
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
30 changes: 22 additions & 8 deletions docs/releasing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,52 @@
# Releasing

To initiate a new production deployment:

```sh
script/release vX.Y.Z
```

See `script/release --help` for more information.

> **Note:**
> Every production release will request an approval by the select few people before it can proceed.
> [!NOTE]
> Deployment workflow requires maintainer approval to run.
Comment thread
iamazeem marked this conversation as resolved.

What this does is:

- Builds Linux binaries on Ubuntu;
- Builds and signs Windows binaries on Windows;
- Builds, signs, and notarizes macOS binaries on macOS;
- Uploads all release artifacts to a new GitHub Release;
- A new git tag `vX.Y.Z` is created in the remote repository;
- The changelog is [generated from the list of merged pull requests](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes);
- Updates cli.github.com with the contents of the new release;
- Updates [GitHub CLI marketing site](https://cli.github.com) with the contents of the new release;
Comment thread
iamazeem marked this conversation as resolved.
- Updates the [`gh` Homebrew formula](https://github.com/williammartin/homebrew-core/blob/master/Formula/g/gh.rb) in the [`homebrew/homebrew-core` repo](https://github.com/search?q=repo%3AHomebrew%2Fhomebrew-core+%22gh%22+in%3Atitle&type=pullrequests).

> [!NOTE]
> `Homebrew/formulae.brew.sh` makes new formula versions available every 15 minutes through scheduled [CI workflow](https://github.com/Homebrew/formulae.brew.sh/actions/workflows/tests.yml).
Comment thread
iamazeem marked this conversation as resolved.
>
> For more information, see https://docs.brew.sh/Formula-Cookbook#an-introduction

To test out the build system while avoiding creating an actual release:

```sh
script/release --staging vX.Y.Z --branch patch-1 -p macos
```

The build artifacts will be available via `gh run download <RUN> -n macos`.

## General guidelines

* Features to be released should be reviewed and approved at least one day prior to the release.
* Feature releases should bump up the minor version number.
* Breaking releases should bump up the major version number. These should generally be rare.
- Features to be released should be reviewed and approved at least one day prior
to the release.
- Feature releases should bump up the minor version number.
- Breaking releases should bump up the major version number. These should
generally be rare.

## Test the build system locally

A local release can be created for testing without creating anything official on the release page.
A local release can be created for testing without creating anything official on
the release page.

1. Make sure GoReleaser is installed: `brew install goreleaser`
2. `script/release --local`
Expand All @@ -45,5 +58,6 @@ Occasionally, it might be necessary to clean up a bad release and re-release.

1. Delete the release and associated tag
2. Re-release and monitor the workflow run logs
3. Open pull request updating [`gh` Homebrew formula](https://github.com/williammartin/homebrew-core/blob/master/Formula/g/gh.rb) with new SHA versions, linking the previous PR
3. Open pull request updating [`gh` Homebrew formula](https://github.com/williammartin/homebrew-core/blob/master/Formula/g/gh.rb)
with new SHA versions, linking the previous PR
4. Verify resulting Debian and RPM packages, Homebrew formula