Skip to content

Commit

Permalink
[chore] Update release procedure (open-telemetry#11538)
Browse files Browse the repository at this point in the history 
<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description

* Minor formatting updates
* Remove notice about being an approver in all three repos, as the
**release manager** section below says it is not necessary.
* Provide convenience commands for creating the release branch with Git.
* Put commands on separate lines to make them more obvious and easier to
copy.
* Add a note about GPG errors if signing was not set up.
* Add a note about handling workflow fixes in
opentelemetry-collector-releases
  • Loading branch information
@evan-bradley @HongChenTW
evan-bradley authored and HongChenTW committed Dec 19, 2024
1 parent c54e8be commit 12ced3f
Showing 1 changed file with 77 additions and 30 deletions.
107 changes: 77 additions & 30 deletions docs/release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,87 +3,123 @@
Collector build and testing is currently fully automated. However there are still certain operations that need to be performed manually in order to make a release.

We release both core and contrib collectors with the same versions where the contrib release uses the core release as a dependency. We’ve divided this process into four sections. A release engineer must release:

1. The [Core](#releasing-opentelemetry-collector) collector, including the collector builder CLI tool.
1. The [Contrib](#releasing-opentelemetry-collector-contrib) collector.
1. The [artifacts](#producing-the-artifacts)

**Important Note:** You’ll need to be able to sign git commits/tags in order to be able to release a collector version. Follow [this guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) to setup it up.

**Important Note:** You’ll need to be an approver for both the repos in order to be able to make the release. This is required as you’ll need to push tags and commits directly to the following repositories:

* [open-telemetry/opentelemetry-collector](https://github.com/open-telemetry/opentelemetry-collector)
* [open-telemetry/opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib)
* [open-telemetry/opentelemetry-collector-releases](https://github.com/open-telemetry/opentelemetry-collector-releases)
**Important Note:** You’ll need to be able to sign git commits/tags in order to be able to release a collector version. Follow [this guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) to set it up.

## Release manager

A release manager is the person responsible for a specific release. While the manager might request help from other folks, they are ultimately responsible for the success of a release.

In order to have more people comfortable with the release process, and in order to decrease the burden on a small number of volunteers, all core approvers are release managers from time to time, listed under the [Release Schedule](#release-schedule) section. That table is updated at every release, with the current manager adding themselves to the bottom of the table, removing themselves from the top of the table.

It is possible that a core approver isn't a contrib approver. In that case, the release manager should coordinate with a contrib approver for the steps requiring such role, like the publishing of tags.
It is possible that a core approver isn't a contrib approver. In that case, the release manager should coordinate with a contrib approver for the steps requiring this role, such as branch creation or tag publishing.

## Releasing opentelemetry-collector

1. Update Contrib to use the latest in development version of Core by running `make update-otel` in Contrib root directory. This is to ensure that the latest core does not break contrib in any way. If it results in any changes, submit a PR to Contrib.
1. Update Contrib to use the latest in development version of Core by running `make update-otel` in Contrib root directory. This is to ensure that the latest core does not break contrib in any way. If it results in any changes, submit a PR to Contrib. If you are unable to run `make update-otel`, it is possible to skip this step and resolve conflicts with Contrib after Core is released, but this is generally inadvisable.
- 🛑 **Do not move forward until this PR is merged.**

2. Determine the version number that will be assigned to the release. Usually, 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.84.0`.
Check if stable modules have any changes since the last release by running `make check-changes PREVIOUS_VERSION=v1.0.0 MODSET=stable`. If there are no changes, there is no need to release new version for stable modules.
If there are changes found but .chloggen directory doesn't have any corresponding entries, add missing changelog entries. If the changes are insignificant, consider not releasing a new version for stable modules.
1. Determine the version number that will be assigned to the release. Usually, 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.84.0`.
Check if stable modules have any changes since the last release by running the following:
- `make check-changes PREVIOUS_VERSION=v1.x.x MODSET=stable`.

If there are no changes, there is no need to release new version for stable
modules. If there are changes found but .chloggen directory doesn't have any
corresponding entries, add missing changelog entries. If the changes are
insignificant, consider not releasing a 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 halted**.
1. 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 halted**.
- When prompted, enter the version numbers determined in Step 2, but do not include a leading `v`.
- If not intending to release stable modules, 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.** 🛑

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,
- `make push-tags MODSET=stable` for stable modules group, only if there were changes since the last release.
1. Check out main and ensure it has the "Prepare release" commit in your local
copy by pulling in the latest from `open-telemetry/opentelemetry-collector`
Use this commit to create a branch named `release/<release-series>` (e.g.
`release/v0.85.x`). Push the new branch to
`open-telemetry/opentelemetry-collector`. Assuming your upstream remote is
named `upstream`, you can try the following commands:
- `git checkout main && git fetch upstream && git rebase upstream/main`
- `git switch -c release/<release series>`
- `git push -u upstream release/<release series>`

2. 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 the beta modules group,
- `make push-tags MODSET=stable` for the stable modules group, only if there were changes since the last release.

If you set your remote using `https` you need to include `REMOTE=https://github.com/open-telemetry/opentelemetry-collector.git` in each command.

If you set your remote using `https` you need to include `REMOTE=https://github.com/open-telemetry/opentelemetry-collector.git` in each command. Wait for the new tag build to pass successfully.
3. Wait for the new tag build to pass successfully.

6. A new `v0.85.0` source code 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.
4. A new `v0.85.0` source code 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.

## Releasing opentelemetry-collector-contrib

1. Open a PR to Contrib to use the newly released Core version and set it to Ready for Review.
1. Open a PR to Contrib to use the newly released Core version by doing the following:
- Manually update `dist.version`, `dist.otelcol_version` and core collector module versions in `cmd/otelcontribcol/builder-config.yaml`
- Manually update `dist.version`, `dist.otelcol_version` and core collector module versions in `cmd/oteltestbedcol/builder-config.yaml`
- Run `make genotelcontribcol genoteltestbedcol`
- Commit the changes
- Run `make update-otel OTEL_VERSION=v0.85.0 OTEL_STABLE_VERSION=v1.1.0`
- If there is no new stable version released in core collector, use the current stable module version in contrib as `OTEL_STABLE_VERSION`.
- If you were unable to run `make update-otel` before releasing core, fix any errors from breaking changes.
- Commit the changes
- Open a PR
- Open the PR
- 🛑 **Do not move forward until this PR is merged.** 🛑

2. Manually run the action [Automation - Prepare Release](https://github.com/open-telemetry/opentelemetry-collector-contrib/actions/workflows/prepare-release.yml). When prompted, enter the version numbers determined in Step 1, but do not include a leading `v`. This action will create a pull request to update the changelog and version numbers in the repo. **While this PR is open all merging in Contrib should be halted**.
1. Manually run the action [Automation - Prepare Release](https://github.com/open-telemetry/opentelemetry-collector-contrib/actions/workflows/prepare-release.yml). When prompted, enter the version numbers determined in Step 1, but do not include a leading `v`. This action will create a pull request to update the changelog and version numbers in the repo. **While this PR is open all merging in Contrib should be halted**.
- 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. 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`.
1. Check out main and ensure it has the "Prepare release" commit in your local
copy by pulling in the latest from
`open-telemetry/opentelemetry-collector-contrib`. Use this commit to create a
branch named `release/<release-series>` (e.g. `release/v0.85.x`). Push the
new branch to `open-telemetry/opentelemetry-collector-contrib`. Assuming your
upstream remote is named `upstream`, you can try the following commands:
- `git checkout main && git fetch upstream && git rebase upstream/main`
- `git switch -c release/<release series>`
- `git push -u upstream release/<release series>`

1. Make sure you are on `release/<release-series>`. Tag all the module groups with the new release version by running:
- `make push-tags MODSET=contrib-base`

If you set your remote using `https` you need to include `REMOTE=https://github.com/open-telemetry/opentelemetry-collector-contrib.git` in each command.

4. 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.
1. Wait for the new tag build to pass successfully.

5. 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.
1. 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

The last step of the release process creates artifacts for the new version of the collector and publishes images to Dockerhub. The steps in this portion of the release are done in the [opentelemetry-collector-releases](https://github.com/open-telemetry/opentelemetry-collector-releases) repo.

1. Update the `./distributions/**/manifest.yaml` files to include the new release version.

2. Update the builder version in `OTELCOL_BUILDER_VERSION` to the new release in the `Makefile`. While this might not be strictly necessary for every release, this is a good practice.
1. Update the builder version in `OTELCOL_BUILDER_VERSION` to the new release in the `Makefile`. While this might not be strictly necessary for every release, this is a good practice.

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).
1. 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.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.
1. Check out main and ensure it has the "Prepare release" commit in your local
copy by pulling in the latest from
`open-telemetry/opentelemetry-collector-releases`. Assuming your upstream
remote is named `upstream`, you can try running:
- `git checkout main && git fetch upstream && git rebase upstream/main`

2. Create a tag for the new release version by running:
- `make push-tags TAG=v0.85.0`

If you set your remote using `https` you need to include `REMOTE=https://github.com/open-telemetry/opentelemetry-collector-contrib.git` in each command.

5. Ensure the "Release Core", "Release Contrib", "Release k8s", and "Builder - Release" actions pass, this will
3. Wait for the new tag build to pass successfully.

4. Ensure the "Release Core", "Release Contrib", "Release k8s", and "Builder - Release" actions pass, this will

1. push new container images to `https://hub.docker.com/repository/docker/otel/opentelemetry-collector`, `https://hub.docker.com/repository/docker/otel/opentelemetry-collector-contrib` and `https://hub.docker.com/repository/docker/otel/opentelemetry-collector-k8s`

Expand All @@ -110,6 +146,17 @@ The last step of the release process creates artifacts for the new version of th
done;
```

6. `unable to tag modules: git tag failed for v0.112.0: unable to create tag:
"error: gpg failed to sign the data:`. Make sure you have GPG set up to sign
commits. You can run `gpg --gen-key` to generate a GPG key.

7. When using a new GitHub Actions workflow in opentelemetry-collector-releases
for the first time during a release, a workflow may fail. If it is possible
to fix the workflow, you can update the release tag to the commit with the
fix and re-run the release; it is safe to re-run the workflows that already
succeeded. Publishing container images can be done multiple times, and
publishing artifacts to GitHub will fail without any adverse effects.

## Bugfix releases

### Bugfix release criteria
Expand Down

0 comments on commit 12ced3f

Please sign in to comment.