Skip to content

Commit

Permalink
[chore] Update the release doc (#8306)
Browse files Browse the repository at this point in the history 
The following changes are applied:
1. Move the contrib draft PR creation to the first step. This is
required to be done before the core release, because some changes may be
needed in the core codebase to resolve possible core/contrib integration
issues which was the case with the 0.84.0 release.
2. Add a missing `v` prefix for OTEL_RC_VERSION env var in step 8.
3. Rotate the schedule
4. Update 0.55.0 version in the examples to 0.85.0. It was inconsistent
with using the latest version for the stable module set
5. Mention CHANGELOG-API in step 7
  • Loading branch information
@dmitryax
dmitryax committed Aug 30, 2023
1 parent 064df80 commit 4fbf6c0
Showing 1 changed file with 14 additions and 14 deletions.
28 changes: 14 additions & 14 deletions docs/release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,18 +25,18 @@ It is possible that a core approver isn't a contrib approver. In that case, the

## Releasing opentelemetry-collector

1. Determine the version number that will be assigned to the release. During the beta phase, we increment the minor version number and set the patch number to 0. In this document, we are using `v0.55.0` as the version to be released, following `v0.54.0`.
Check if stable modules have any changes since the last release by running `make check-changes PREVIOUS_VERSION=v1.0.0-rc9 MODSET=stable`. If there are no changes, there is no need to release new version for stable modules.
1. Update Contrib to use the latest in development version of Core. Run `make update-otel` in Contrib root directory and if it results in any changes submit a draft PR to Contrib. Ensure the CI passes before proceeding. This is to ensure that the latest core does not break contrib in any way. We’ll update it once more to the final release number later.

2. Manually run the action [Automation - Prepare Release](https://github.com/open-telemetry/opentelemetry-collector/actions/workflows/prepare-release.yml). This action will create an issue to track the progress of the release and a pull request to update the changelog and version numbers in the repo. **While this PR is open all merging in Core should be haulted**.
2. Determine the version number that will be assigned to the release. During the beta phase, we increment the minor version number and set the patch number to 0. In this document, we are using `v0.85.0` as the version to be released, following `v0.54.0`.
Check if stable modules have any changes since the last release by running `make check-changes PREVIOUS_VERSION=v1.0.0-rcv0014 MODSET=stable`. If there are no changes, there is no need to release new version for stable modules.

3. Manually run the action [Automation - Prepare Release](https://github.com/open-telemetry/opentelemetry-collector/actions/workflows/prepare-release.yml). This action will create an issue to track the progress of the release and a pull request to update the changelog and version numbers in the repo. **While this PR is open all merging in Core should be haulted**.
- When prompted, enter the version numbers determined in Step 1, but do not include a leading `v`.
- If not intending to release stable modeles, do not specify a version for `Release candidate version stable`.
- If the PR needs updated in any way you can make the changes in a fork and PR those changes into the `prepare-release-prs/x` branch. You do not need to wait for the CI to pass in this prep-to-prep PR.
- 🛑 **Do not move forward until this PR is merged.** 🛑

3. Update Contrib to use the latest in development version of Core. Run `make update-otel` in Contrib root directory and if it results in any changes submit a PR to Contrib with the changes as draft. This is to ensure that the latest core does not break contrib in any way. We’ll update it once more to the final release number later.

4. Check out the commit created by merging the PR created by `Automation - Prepare Release` (e.g. `prepare-release-prs/0.55.0`) and create a branch named `release/<release-series>` (e.g. `release/v0.55.x`). Push the new branch to `open-telemetry/opentelemetry-collector`.
4. Check out the commit created by merging the PR created by `Automation - Prepare Release` (e.g. `prepare-release-prs/0.85.0`) and create a branch named `release/<release-series>` (e.g. `release/v0.85.x`). Push the new branch to `open-telemetry/opentelemetry-collector`.

5. Make sure you are on `release/<release-series>`. Tag the module groups with the new release version by running:
- `make push-tags MODSET=beta` for beta modules group,
Expand All @@ -46,10 +46,10 @@ It is possible that a core approver isn't a contrib approver. In that case, the

6. The release script for the collector builder should create a new GitHub release for the builder. This is a separate release from the core, but we might join them in the future if it makes sense.

7. A new `v0.55.0` release should be automatically created on Github by now. Edit it and use the contents from the CHANGELOG.md as the release's description.
7. A new `v0.85.0` release should be automatically created on Github by now. Edit it and use the contents from the CHANGELOG.md and CHANGELOG-API.md as the release's description.

8. If you created a draft PR to Contrib in step 3, update the PR to use the newly released Core version and set it to Ready for Review.
- Run `make update-otel OTEL_VERSION=v0.55.0 OTEL_RC_VERSION=1.0.0-rcv0014`
- Run `make update-otel OTEL_VERSION=v0.85.0 OTEL_RC_VERSION=v1.0.0-rcv0014`
- Manually update `cmd/otelcontribcol/builder-config.yaml`
- Manually update `cmd/oteltestbedcol/builder-config.yaml`
- Run `make genotelcontribcol`
Expand All @@ -62,11 +62,11 @@ It is possible that a core approver isn't a contrib approver. In that case, the
- If the PR needs updated in any way you can make the changes in a fork and PR those changes into the `prepare-release-prs/x` branch. You do not need to wait for the CI to pass in this prep-to-prep PR.
- 🛑 **Do not move forward until this PR is merged.** 🛑

2. Check out the commit created by merging the PR created by `Automation - Prepare Release` (e.g. `prepare-release-prs/0.55.0`) and create a branch named `release/<release-series>` (e.g. `release/v0.55.x`). Push the new branch to `open-telemetry/opentelemetry-collector-contrib`.
2. Check out the commit created by merging the PR created by `Automation - Prepare Release` (e.g. `prepare-release-prs/0.85.0`) and create a branch named `release/<release-series>` (e.g. `release/v0.85.x`). Push the new branch to `open-telemetry/opentelemetry-collector-contrib`.

3. Make sure you are on `release/<release-series>`. Tag all the module groups (`contrib-base`) with the new release version by running the `make push-tags MODSET=contrib-base` command. If you set your remote using `https` you need to include `REMOTE=https://github.com/open-telemetry/opentelemetry-collector-contrib.git` in each command. Wait for the new tag build to pass successfully.

4. A new `v0.55.0` release should be automatically created on Github by now. Edit it and use the contents from the CHANGELOG.md as the release's description.
4. A new `v0.85.0` release should be automatically created on Github by now. Edit it and use the contents from the CHANGELOG.md as the release's description.

## Producing the artifacts

Expand All @@ -79,7 +79,7 @@ The last step of the release process creates artifacts for the new version of th
3. Create a pull request with the change and ensure the build completes successfully. See [example](https://github.com/open-telemetry/opentelemetry-collector-releases/pull/71).
- 🛑 **Do not move forward until this PR is merged.** 🛑

4. Check out the commit created by merging the PR and tag with the new release version by running the `make push-tags TAG=v0.55.0` command. If you set your remote using `https` you need to include `REMOTE=https://github.com/open-telemetry/opentelemetry-collector-releases.git` in each command. Wait for the new tag build to pass successfully.
4. Check out the commit created by merging the PR and tag with the new release version by running the `make push-tags TAG=v0.85.0` command. If you set your remote using `https` you need to include `REMOTE=https://github.com/open-telemetry/opentelemetry-collector-releases.git` in each command. Wait for the new tag build to pass successfully.

5. Ensure the "Release" action passes, this will

Expand All @@ -89,7 +89,7 @@ The last step of the release process creates artifacts for the new version of th

## Troubleshooting

1. `unknown revision internal/coreinternal/v0.55.0` -- This is typically an indication that there's a dependency on a new module. You can fix it by adding a new `replaces` entry to the `go.mod` for the affected module.
1. `unknown revision internal/coreinternal/v0.85.0` -- This is typically an indication that there's a dependency on a new module. You can fix it by adding a new `replaces` entry to the `go.mod` for the affected module.
2. `commitChangesToNewBranch failed: invalid merge` -- This is a [known issue](https://github.com/open-telemetry/opentelemetry-go-build-tools/issues/47) with our release tooling. The current workaround is to clone a fresh copy of the repository and try again. Note that you may need to set up a `fork` remote pointing to your own fork for the release tooling to work properly.
3. `could not run Go Mod Tidy: go mod tidy failed` when running `multimod` -- This is a [known issue](https://github.com/open-telemetry/opentelemetry-go-build-tools/issues/46) with our release tooling. The current workaround is to run `make gotidy` manually after the multimod tool fails and commit the result.
4. `Incorrect version "X" of "go.opentelemetry.io/collector/component" is included in "X"` in CI after `make update-otel` -- It could be because the make target was run too soon after updating Core and the goproxy hasn't updated yet. Try running `export GOPROXY=direct` and then `make update-otel`.
Expand Down Expand Up @@ -136,7 +136,7 @@ The following documents the procedure to release a bugfix
2. Create a pull request to update version number against the `release/<release-series>` branch.
3. Once those changes have been merged, create a pull request to the `main` branch from the `release/<release-series>` branch.
4. Enable the **Merge pull request** setting in the repository's **Settings** tab.
5. Tag all the modules with the new release version by running the `make add-tag` command (e.g. `make add-tag TAG=v0.55.0`). Push them to `open-telemetry/opentelemetry-collector` with `make push-tag TAG=v0.55.0`. Wait for the new tag build to pass successfully.
5. Tag all the modules with the new release version by running the `make add-tag` command (e.g. `make add-tag TAG=v0.85.0`). Push them to `open-telemetry/opentelemetry-collector` with `make push-tag TAG=v0.85.0`. Wait for the new tag build to pass successfully.
6. **IMPORTANT**: The pull request to bring the changes from the release branch *MUST* be merged using the **Merge pull request** method, and *NOT* squashed using “**Squash and merge**”. This is important as it allows us to ensure the commit SHA from the release branch is also on the main branch. **Not following this step will cause much go dependency sadness.**
7. Once the branch has been merged, it will be auto-deleted. Restore the release branch via GitHub.
8. Once the patch is release, disable the **Merge pull request** setting.
Expand All @@ -145,10 +145,10 @@ The following documents the procedure to release a bugfix
| Date | Version | Release manager |
|------------|---------|-----------------|
| 2023-08-28 | v0.84.0 | @dmitryax |
| 2023-09-11 | v0.85.0 | @codeboten |
| 2023-09-25 | v0.86.0 | @bogdandrutu |
| 2023-10-09 | v0.87.0 | @Aneurysm9 |
| 2023-10-23 | v0.88.0 | @mx-psi |
| 2023-11-06 | v0.89.0 | @jpkrohling |
| 2023-11-20 | v0.90.0 | @djaglowski |
| 2023-12-04 | v0.84.0 | @dmitryax |

0 comments on commit 4fbf6c0

Please sign in to comment.