Skip to content

RELEASING.md

Latest commit

 

History

History
289 lines (216 loc) · 10.1 KB

RELEASING.md

File metadata and controls

289 lines (216 loc) · 10.1 KB
Raw

Releasing

This document describes the release process for the OTel Arrow repository. A single release version covers both the Go components (under go/ and collector/) and the Rust workspace (under rust/otap-dataflow/).

Overview

The repository uses two GitHub Actions workflows to manage releases:

  1. Prepare Release: Renders pending changelog entries, bumps versions, and opens a pull request.
  2. Push Release: Publishes opted-in Rust crates, creates git tags, and publishes the GitHub release.

This two-step process ensures that all changes are reviewed before the release is published.

Prerequisites

  1. Maintainer Access: Only repository maintainers can trigger the release workflows.
  2. Clean Repository: Ensure your local repository has no uncommitted changes.
  3. Pending changelog entries: Each user-facing PR should have added a YAML fragment under go/.chloggen/ (for Go changes) or rust/otap-dataflow/.chloggen/ (for Rust changes). The release workflow collapses these into the appropriate CHANGELOG at release time.
  4. Protected environment: The release GitHub environment exists with the required maintainers as approvers.
  5. Trusted publishing: crates.io trusts .github/workflows/push-release.yml in this repository with the release environment.

Changelog management

Contributors do not edit go/CHANGELOG.md or rust/otap-dataflow/CHANGELOG.md directly. Instead, each PR adds a YAML fragment to the corresponding .chloggen/ directory by copying TEMPLATE.yaml to a new file (see the README in each directory). The changelog workflow enforces this on PRs that target main.

At release time, the Prepare Release workflow runs make chlog-update VERSION=v<version>, which:

  • Renders all pending entries from go/.chloggen/*.yaml into go/CHANGELOG.md under a new ## v<version> heading.
  • Renders all pending entries from rust/otap-dataflow/.chloggen/*.yaml into rust/otap-dataflow/CHANGELOG.md under a new ## v<version> heading.
  • Deletes the consumed .yaml entry files.

You can preview what the next release will look like locally:

make chlog-install
make chlog-preview

Release Process

Step 1: Confirm pending changelog entries

  1. Inspect go/.chloggen/ and rust/otap-dataflow/.chloggen/ and confirm the pending entries describe the changes you want to release.
  2. Optionally run make chlog-preview locally for a rendered view.
  3. Commit any final changes to the main branch.

Step 2: Run Prepare Release Workflow

  1. Go to the Actions tab in the GitHub repository.
  2. Select the "Prepare Release" workflow.
  3. Click "Run workflow".
  4. Fill in the required inputs:
    • Version: The new version number (e.g., 0.48.0).
    • Dry run: Check this box to preview changes without making them.

Step 3: Review Dry Run (Recommended)

Before making actual changes, run the workflow in dry-run mode:

  1. Set "Dry run mode" to true.
  2. Review the output to ensure all planned changes are correct.
  3. Verify that the version increment makes sense.
  4. Check the rendered release-notes preview (with ## Go and ## Rust sections).

Step 4: Execute Release Preparation

  1. Run the workflow again with "Dry run mode" set to false.
  2. The workflow will:
    • Validate the version format and increment.
    • Verify that the merge queue is empty and that main does not change while the release contents are generated.
    • Auto-generate umbrella chloggen entries summarizing renovate[bot] and dependabot[bot] PRs merged since the last release tag (one per tree, skipped if none).
    • Render pending chloggen entries into go/CHANGELOG.md and rust/otap-dataflow/CHANGELOG.md, deleting the consumed .yaml entries.
    • Bump the Rust workspace + root package versions in rust/otap-dataflow/Cargo.toml.
    • Create a release branch (otelbot/release-vX.Y.Z) and open a pull request.

Step 5: Review and Merge PR

  1. Review the automatically created pull request.
  2. Verify that:
    • Both go/CHANGELOG.md and rust/otap-dataflow/CHANGELOG.md render the expected entries.
    • rust/otap-dataflow/Cargo.toml reflects the new version.
  3. Ensure all CI checks pass.
  4. Merge the pull request. While it is open, the required changelog check blocks every other pull request from merging.

Step 6: Run Push Release Workflow

  1. Go to the Actions tab in the GitHub repository.
  2. Select the "Push Release" workflow.
  3. Click "Run workflow".
  4. Fill in the required inputs:
    • Version: The same version number used in the prepare step (e.g., 0.48.0).
    • Dry run: Check this box to preview what will happen.

Step 7: Review Push Release Dry Run (Recommended)

Before publishing the release, run the push workflow in dry-run mode:

  1. Set "Dry run mode" to true.
  2. Review the output to ensure all git tags and release content look correct.

Step 8: Publish Release

  1. Run the push release workflow again with "Dry run mode" set to false.
  2. The workflow will:
    • Resolve the merged otelbot/release-vX.Y.Z pull request and use its merge commit as the release commit.
    • Obtain a short-lived crates.io token through trusted publishing.
    • Publish otel-arrow-dfe-pdata-views, or skip the version if it already exists.
    • Wait until crates.io reports the version before creating release tags.
    • Create git tags for the main release, the Go modules, and the Rust workspace at that release commit.
    • Publish the GitHub release with the combined changelog content.

Changes merged into main after the release pull request are not included in these tags. Their .chloggen/ entries remain pending and are rendered into the next release. Normal pull request merges resume after the release pull request merges, even if the tags have not been created yet.

The following git tags are created:

  • vX.Y.Z - Main release tag.
  • go/vX.Y.Z - Go module tag (covers github.com/open-telemetry/otel-arrow/go).
  • rust/otap-dataflow/vX.Y.Z - Rust workspace tag.

Supported Components

The release process handles:

Go Modules:

  • github.com/open-telemetry/otel-arrow/go

Rust Workspace:

  • rust/otap-dataflow/ aggregate git tag.
  • otel-arrow-dfe-pdata-views on crates.io. All other Rust workspace packages remain unpublished during the pilot.

Troubleshooting

Common Issues

"No .chloggen/*.yaml entry was added or modified in this PR"

  • Copy go/.chloggen/TEMPLATE.yaml (for Go changes) or rust/otap-dataflow/.chloggen/TEMPLATE.yaml (for Rust changes) to a new .yaml file in the same directory, fill in the fields, and commit it.
  • If the PR truly doesn't need an entry (internal refactors, dev-only dependency bumps, doc-only edits), include chore in the PR title or apply the chore label.

"The CHANGELOG files were modified directly"

  • Revert the direct edit. Add a .chloggen/*.yaml entry instead.

"Version v<X.Y.Z> not found in go/CHANGELOG.md"

  • Ensure the Prepare Release workflow has run and its PR has merged before running Push Release.

"Repository has uncommitted changes"

  • Commit or stash any local changes before running the workflow.

"Version is not greater than last version"

  • Ensure the new version follows semantic versioning and is greater than the current version.

crates.io trusted publishing authentication fails

  • Confirm the crate's trusted publisher names open-telemetry/otel-arrow, workflow push-release.yml, and environment release.
  • Confirm the workflow was started from an event and ref allowed by the protected release environment.
  • Do not restore or add a long-lived crates.io token to the workflow.

Manual Recovery

If the workflow fails partway through:

  1. Check whether otel-arrow-dfe-pdata-views@X.Y.Z exists on crates.io.
  2. If it exists, publication is irreversible. Re-run Push Release with the same version. The publisher skips the existing crate before resuming tags and the GitHub release.
  3. Never attempt to replace an existing crates.io version. Prepare a new patch version if the published contents are wrong.
  4. If publication did not occur, fix the underlying issue and re-run the workflow normally.

Do not yank a version merely because a later tag or GitHub release step failed. Yanking prevents normal dependency resolution and does not permit republishing the same version.

Emergency Release Process

In case the automated workflow cannot be used, you can create a manual release:

  1. Render the pending chloggen entries locally:

    make chlog-install
make chlog-update VERSION=vX.Y.Z

  2. Bump the Rust workspace versions:

    sed -i 's/^version = "[0-9]\+\.[0-9]\+\.[0-9]\+"/version = "X.Y.Z"/g' \
  rust/otap-dataflow/Cargo.toml

  3. Commit the changes, open and merge a PR.

  4. From the merged release commit, publish or verify the views crate with a short-lived crates.io token:

    cd rust/otap-dataflow
export CARGO_REGISTRY_TOKEN="REPLACE_WITH_SHORT_LIVED_TOKEN"
cargo xtask crates-publish publish X.Y.Z
unset CARGO_REGISTRY_TOKEN
cd ../..

  5. Create and push the release tags:

    git tag -a vX.Y.Z -m "Release vX.Y.Z"
git tag -a go/vX.Y.Z -m "Release go/vX.Y.Z"
git tag -a rust/otap-dataflow/vX.Y.Z \
  -m "Release rust/otap-dataflow/vX.Y.Z"
git push origin vX.Y.Z go/vX.Y.Z \
  rust/otap-dataflow/vX.Y.Z

  6. Create a GitHub release manually.

Version Strategy

  • All Go components and the Rust workspace currently share a single release version. Rust crates track the Go release version going forward.
  • Versions follow Semantic Versioning.
  • This project is pre-1.0; minor-version releases may include breaking changes.
  • Pre-release versions are not currently supported through the automated workflow.
  • Only otel-arrow-dfe-pdata-views is published to crates.io during the pilot. Consume every other Rust crate using the Rust workspace git tag.