diff --git a/docs/developer/release/2-cherry-pick-commits.md b/docs/developer/release/2-cherry-pick-commits.md deleted file mode 100644 index c1cf28674f..0000000000 --- a/docs/developer/release/2-cherry-pick-commits.md +++ /dev/null @@ -1,18 +0,0 @@ -# Cherry Pick Commits - -Any commits not on the release branch need to be cherry-picked over to it. - -## Before you begin - -1. If the release branch already has all code changes on it, skip this step. - -## Steps - -1. Create PR(s) to cherry-pick additional commits into the release branch as needed from main: - - ``` - git cherry-pick -x COMMIT_SHA - ``` - - If there are several commits to cherry-pick, consider using one branch to cherry-pick to and ask reviewers to review commit-by-commit. - - - For example, refer to PR [#3188](https://github.com/grafana/agent/pull/3188) and [#3185](https://github.com/grafana/agent/pull/3185). diff --git a/docs/developer/release/3-update-version-in-code.md b/docs/developer/release/3-update-version-in-code.md index 1508872c79..14b42903d0 100644 --- a/docs/developer/release/3-update-version-in-code.md +++ b/docs/developer/release/3-update-version-in-code.md @@ -1,6 +1,7 @@ -# 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 @@ -8,53 +9,80 @@ The project must be updated to reference the upcoming release tag whenever a new 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] is used by the CI to ensure that templates and generated files are in sync. -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 VERSION file on the `release/` branch should point to the stable (or patch) version you're about to release. - > **NOTE**: Only perform this step for patch releases, and make sure that - > the change is not pushed to the main branch. +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`). - After updating `VERSION`, run: +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`. - ```bash - make generate-versioned-files - ``` +After updating the VERSION file, run: - 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). +```bash +make generate-versioned-files +``` +## 2. Update the "main" branch -6. Create a PR to merge to `release/VERSION_PREFIX` (must be merged before continuing). +Examples: - - 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. +* 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 + +For a First Release Candidate or a Patch Release, add a new header under `Main (unreleased)` for `VERSION`. + +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`. + +After updating the VERSION file, run: + +```bash +make generate-versioned-files +``` + +[VERSION-file]: https://github.com/grafana/alloy/blob/main/VERSION \ No newline at end of file diff --git a/docs/developer/release/7-test-release.md b/docs/developer/release/7-test-release.md index b2f96d9ad6..dab2b10ea5 100644 --- a/docs/developer/release/7-test-release.md +++ b/docs/developer/release/7-test-release.md @@ -6,4 +6,4 @@ Validate the new version is working by running it incrementally in all dogfoodin 1. Validate performance metrics are consistent with the prior version. -2. Validate components are healthy. +2. Validate components are healthy. \ No newline at end of file diff --git a/docs/developer/release/README.md b/docs/developer/release/README.md index 17a5d57bfd..7f9d345e48 100644 --- a/docs/developer/release/README.md +++ b/docs/developer/release/README.md @@ -17,45 +17,42 @@ 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) +## 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. [Test Release](./7-test-release.md) +5. [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. [Test Release](./7-test-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) +8. [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) +## 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. [Test Release](./7-test-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) -## 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