Skip to content
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

Jump to bottom

Update the release steps for "Cherry Pick Commits" and "Update Version in Code" #1783

Merged
merged 3 commits into from
Oct 7, 2024
Merged

Update the release steps for "Cherry Pick Commits" and "Update Version in Code" #1783

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ff36f44
Combine two release steps into one
ptodev Sep 27, 2024
9635d5e
Add back "make generate-versioned-files"
ptodev Sep 30, 2024
e2fb0e9
Bring back Test Release step
ptodev Sep 30, 2024
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
18 changes: 0 additions & 18 deletions docs/developer/release/2-cherry-pick-commits.md
View file
Open in desktop

This file was deleted.

82 changes: 48 additions & 34 deletions docs/developer/release/3-update-version-in-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,60 +1,74 @@
# Update Version in Code
# Update the "main" and "release/" branches

The project must be updated to reference the upcoming release tag whenever a new release is being made.
You need to update the CHANGELOG and the [VERSION file][VERSION-file].
You may also need to cherry pick commits on the `release/` branch.

## Before you begin

1. Determine the [VERSION](concepts/version.md).

2. Determine the [VERSION_PREFIX](concepts/version.md)

## Steps
## 1. Update the "release/VERSION_PREFIX" branch

1. Create a branch from `main` for [grafana/alloy](https://github.com/grafana/alloy).
Example PRs:

2. Update the `CHANGELOG.md`:
* [Release Candidate](https://github.com/grafana/alloy/pull/1410).
Here the PR is done on the main branch, before creating the release branch.
You can do this to save time by not having to update the release branch separately.
* [Additional Release Candidate](https://github.com/grafana/alloy/pull/1701)
* [Stable Release](https://github.com/grafana/alloy/pull/1747)
There is no need to update the VERSION file in this PR.
The VERSION file is already pointing to the version being released ever since the `release/` branch was created.
* [Patch Release](https://github.com/grafana/alloy/pull/1767)

1. `CHANGELOG.md` Header
- First Release Candidate or a Patch Release
- Add a new header under `Main (unreleased)` for `VERSION`.
- Additional RCV or SRV
- Update the header `PREVIOUS_RELEASE_CANDIDATE_VERSION` to `VERSION`. The date may need updating.
### 1.1. Add the new version to the CHANGELOG

2. Move the unreleased changes we want to add to the release branch from `Main (unreleased)` to `VERSION`.
For a First Release Candidate (`rc.0`), replace the `Main (unreleased)` header with a new one for `VERSION`.

3. Create a PR to merge to main (must be merged before continuing).
For an Additional Release Candidate or SRV, update the header `PREVIOUS_RELEASE_CANDIDATE_VERSION` to `VERSION`.

- Release Candidate example PR [here](https://github.com/grafana/agent/pull/3065)
- Stable Release example PR [here](https://github.com/grafana/agent/pull/3119)
- Patch Release example PR [here](https://github.com/grafana/agent/pull/3191)
For a patch release, add a new header for `VERSION`.

4. If one doesn't exist yet, create a branch called `release/VERSION_PREFIX` for [grafana/alloy](https://github.com/grafana/alloy).
### 1.2. Cherry pick commits

5. Cherry pick the commit on main from the merged PR in Step 3 from main into the branch from Step 4:
If you need certain changes on the release branch but they're not yet there, cherry-pick them onto the release branch.
In the CHANGELOG, make sure they are listed under the header for the new VERSION and not under `Main (unreleased)`.

```
git cherry-pick -x COMMIT_SHA
```
### 1.3. Update the VERSION file

Delete the `Main (unreleased)` header and anything underneath it as part of the cherry-pick. Alternatively, do it after the cherry-pick is completed.
The [VERSION file][VERSION-file] on the `release/` branch should point to the stable (or patch) version you're about to release.

6. **If you are creating a patch release,** ensure that the file called `VERSION` in your branch matches the version being published, without any release candidate or build information:
The contents of the VERSION file should not contain `rc` information.
Therefore, there is no need to update the VERSION file for additional release candidates (e.g. `rc.1`, `rc.2`).

> **NOTE**: Only perform this step for patch releases, and make sure that
> the change is not pushed to the main branch.
For example:
* If you are going to release `v1.2.0-rc.0`, then the VERSION file should contain `v1.2.0`.
* If you are going to release `v1.5.1`, then the VERSION file should contain `v1.5.1`.

After updating `VERSION`, run:
## 2. Update the "main" branch

```bash
make generate-versioned-files
```
wildum marked this conversation as resolved.
Show resolved Hide resolved
Examples:

Next, commit the changes (including those to `VERSION`, as a workflow will use this version to ensure that the templates and generated files are in sync).
* Release Candidate example PR [here](https://github.com/grafana/alloy/pull/1410)
* Stable Release example PR [here](https://github.com/grafana/alloy/pull/1419)
* Patch Release example PR [here](https://github.com/grafana/alloy/pull/1769)

### 2.1. Add the new version to the CHANGELOG

6. Create a PR to merge to `release/VERSION_PREFIX` (must be merged before continuing).
For a First Release Candidate or a Patch Release, add a new header under `Main (unreleased)` for `VERSION`.

- Release Candidate example PR [here](https://github.com/grafana/agent/pull/3066)
- Stable Release example PR [here](https://github.com/grafana/agent/pull/3123)
- Patch Release example PR [here](https://github.com/grafana/agent/pull/3193)
- The `CHANGELOG.md` was updated in cherry-pick commits prior for this example. Make sure it is all set on this PR.
For an Additional Release Candidate or SRV, update the header `PREVIOUS_RELEASE_CANDIDATE_VERSION` to `VERSION`.

### 2.2. Update the VERSION file

The [VERSION file][VERSION-file] on the "main" branch should point to the next major version.
For example:
* If you are going to release `v1.2.0-rc.0`, then the VERSION file should contain `v1.3.0`.
* If you are going to release `v1.5.1`, then the VERSION file should contain `v1.6.0`.

The reasoning behind this is that any builds of the main branch should contain the next major version they are meant to go to.
If the latest release branch that was cut is `release/1.3`, then `main` is preparing for `1.4.0`.
Any builds of the main branch will therefore be labeled `devel-1.4.0`.

[VERSION-file]: https://github.com/grafana/alloy/blob/main/VERSION
9 changes: 0 additions & 9 deletions docs/developer/release/7-test-release.md
View file
Open in desktop

This file was deleted.

61 changes: 27 additions & 34 deletions docs/developer/release/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,45 +17,38 @@ and the creation of the next Release Candidate.
Once a release is scheduled, a release shepherd is determined. This person will be
responsible for ownership of the following workflows:

## Release Candidate Publish
0. [Ensure our OpenTelemetry Collector dependency has been updated](./0-ensure-otel-dep-updated.md)
1. [Create Release Branch](./1-create-release-branch.md)
2. [Cherry Pick Commits](./2-cherry-pick-commits.md)
3. [Update Version in Code](./3-update-version-in-code.md)
## First release candidate (`rc.0`)
1. [Ensure our OpenTelemetry Collector dependency has been updated](./0-ensure-otel-dep-updated.md)
2. [Create Release Branch](./1-create-release-branch.md)
3. [Update the "main" and "release/" branches](./3-update-version-in-code.md)
4. [Tag Release](./4-tag-release.md)
5. [Publish Release](./6-publish-release.md)
6. [Test Release](./7-test-release.md)
7. [Announce Release](./10-announce-release.md)

## Additional Release Candidate[s] Publish
1. [Cherry Pick Commits](./2-cherry-pick-commits.md)
2. [Update Version in Code](./3-update-version-in-code.md)
3. [Tag Release](./4-tag-release.md)
4. [Publish Release](./6-publish-release.md)
5. [Test Release](./7-test-release.md)
6. [Announce Release](./10-announce-release.md)

## Stable Release Publish
1. [Cherry Pick Commits](./2-cherry-pick-commits.md)
2. [Update Version in Code](./3-update-version-in-code.md)
3. [Tag Release](./4-tag-release.md)
4. [Publish Release](./6-publish-release.md)
5. [Test Release](./7-test-release.md)
6. [Update Helm Charts](./8-update-helm-charts.md)
7. [Update Homebrew](./9-update-homebrew.md)
8. [Announce Release](./10-announce-release.md)
9. [Update OTEL Contrib](./11-update-otel.md)

## Patch Release Publish (latest version)
1. [Cherry Pick Commits](./2-cherry-pick-commits.md)
2. [Update Version in Code](./3-update-version-in-code.md)
3. [Tag Release](./4-tag-release.md)
4. [Publish Release](./6-publish-release.md)
5. [Update Helm Charts](./8-update-helm-charts.md)
6. [Update Homebrew](./9-update-homebrew.md)
7. [Announce Release](./10-announce-release.md)
## Additional release candidate (`rc.1`, `rc.2`...)
1. [Update the "main" and "release/" branches](./3-update-version-in-code.md)
2. [Tag Release](./4-tag-release.md)
3. [Publish Release](./6-publish-release.md)
4. [Announce Release](./10-announce-release.md)

## Stable Release Publish (`1.2.0`, `1.6.0`...)
1. [Update the "main" and "release/" branches](./3-update-version-in-code.md)
2. [Tag Release](./4-tag-release.md)
3. [Publish Release](./6-publish-release.md)
4. [Update Helm Charts](./8-update-helm-charts.md)
5. [Update Homebrew](./9-update-homebrew.md)
6. [Announce Release](./10-announce-release.md)
7. [Update OTEL Contrib](./11-update-otel.md)

## Patch Release Publish - latest version (`1.15.1`, `1.15.2`...)
1. [Update the "main" and "release/" branches](./3-update-version-in-code.md)
2. [Tag Release](./4-tag-release.md)
3. [Publish Release](./6-publish-release.md)
4. [Update Helm Charts](./8-update-helm-charts.md)
5. [Update Homebrew](./9-update-homebrew.md)
6. [Announce Release](./10-announce-release.md)

## Patch Release Publish (older version)
## Patch Release Publish - older version (`1.0.1`, `1.0.2`...)
- Not documented yet (but here are some hints)
- somewhat similar to Patch Release Publish (latest version)
- find the old release branch
Expand Down