Spec/semconv release flow: integration branches finalize their own release PRs#10738
Merged
chalin merged 14 commits intoJul 9, 2026
Merged
Conversation
otelbot-docs
Bot
added
the
missing:docs-approval
otelbot-docs
Bot
added
the
missing:sig-approval
chalin
force-pushed
the
chalin-m24-spec-release-flow-2026-0708
branch
from
July 9, 2026 14:19
61a8300 to
b7f9cce
Compare
- Adds a release mode to pick-branch: when the latest upstream release is newer than the version pinned on main, VERSION is the released tag and the existing integration branch is finalized instead of abandoned. - Reads the submodule pin from .gitmodules and parses it defensively (git-describe-style pins). - Emits MODE=dev|release to $GITHUB_ENV alongside VERSION/BRANCH. - Extracts the workflows' PR logic into a tested helper, scripts/gh/specs/ensure-pr, and replaces the PR-creation step of both workflows with a single step that calls it. - Dev mode: opens the draft integration PR when needed (bootstrapping the branch with an empty commit), as before. - Release mode: creates the non-draft release PR, promotes the existing draft (ready + title + body, written exactly once), or re-syncs the title only so maintainer notes in the body survive daily reruns. - The CLI validates MODE/VERSION/BRANCH from the environment and fails loudly on misconfiguration.
- Drops the opentelemetry-specification and semantic-conventions entries from all-versions.sh: releases of these repos are now handled by the integration workflows, which finalize the accumulated integration branch into the release PR instead of opening a fresh one. - Leaves version-in-file.sh unchanged (still used by the remaining repos and for manual runs).
- The "ensure" idiom obscured what the helper actually does (create the draft or release PR, finalize the draft, re-sync the title); the new name is transparent and matches the workflow step name "Create or finalize pull request". - Renames the script directory and identifiers (`ensurePullRequest()` -> `createOrFinalizePullRequest()`, etc.); no behavior change.
- Replaces the 10-value `{ action }` result with a plain `created | updated | unchanged` outcome string: the `would-*` variants only echoed the caller's own dry-run input, and the bootstrap distinction is an implementation detail that tests assert via the recorded `git` calls instead.
- Collapses each dry-run/write branch pair into a single code path: one tense-neutral log line (`[dry-run]`-prefixed as needed) with only the writes guarded.
- Moves cli.mjs up to `scripts/gh/specs/create-or-finalize-pr.mjs` (shebang + exec bit) so workflows and maintainers invoke it directly — `scripts/gh/specs/create-or-finalize-pr.mjs --spec=otel` — matching how the repo's shell commands are run; the same-named directory keeps the pure library and its tests. - Updates both integration workflows, the usage text, and doc comments accordingly.
- Shrinks the command-file header to purpose + "run with --help": the help text now owns the flag and environment reference (DRY). - Moves cliUsage() from the lib into the command file — it is CLI surface, not library logic; folds the header's GH_TOKEN and branch-checkout notes into a new Environment section. - Prefers the space form for flag values: usage shows `--spec <otel|semconv>` and the workflows invoke `--spec otel|semconv` (`--spec=<value>` remains supported).
- Updates the spec-integration-branches section for the full release lifecycle: - Intro now covers dev-cycle draft PR → finalized release PR, and notes that auto-update-versions.yml excludes the spec repositories (also cross-referenced from the workflow table). - Documents pick-branch's MODE selection and the create-or-finalize-pr final step; run-modes section and examples now cover both helpers. - Adds a refcache entry for the new command's URL, which resolves once this PR lands (same approach as open-telemetry#9682 for pick-branch).
Review feedback: during draft finalization, `gh pr ready` ran before `gh pr edit`. If `edit` failed after `ready` succeeded, the next run saw a non-draft PR and only re-synced the title -- the release body was never written, and the run reported success. Write the title and body first: if `ready` fails, the PR remains a draft and the next run redoes the finalization idempotently. Test improvements from the same review: - Assert the edit-before-ready order, and add a regression test that a failed edit leaves the PR a draft (`pr ready` unreached). - Make the bootstrap-before-`pr create` ordering assertion real: the fake runners can now share an ordered call log; the previous assertion (`git.calls.length > 1`) did not check order. - Reword assertion messages to be positively affirmative.
Review feedback: the new create-or-finalize-pr command documents and is invoked with `--spec <id>`, while pick-branch's usage text and workflow invocations still showed `--spec=<id>`. Align on the space form; the `=` form remains supported and tested.
The finalize mechanics quoted on the page (ready/edit ordering) went stale within one review cycle -- a sign the page owned too much detail. Keep the what/why and the step contracts (MODE meaning, env handoff, maintainer notes preserved); the mechanics live in the helpers' docstrings and --help.
The command wrapper pipes gh's stdout, so the URL that `gh pr create` prints was captured and dropped -- an observability regression from the inline workflow step, which streamed it to the log.
Release-mode finalization becomes three independent, idempotent fixups -- title sync, body sync, draft-to-ready -- governed by one ownership rule: the automation rewrites only text it itself wrote (the dev or release title/body, for any version); once a maintainer edits the title or the body, that field is theirs and is left alone. This heals PRs that previous runs could strand (e.g. a draft manually marked ready kept its draft body forever), re-syncs the stale body along with the title when a newer release lands, stops reverting deliberate maintainer retitles, and lets body notes added during the dev cycle survive finalization. Addresses a bugbot finding on the release-flow PR.
pick-branch wrote the tag returned by `gh release view` to $GITHUB_ENV unvalidated in release mode, and workflow shell steps interpolate it (e.g. `git reset --hard $VERSION`). Git ref syntax rules out word splitting, but a hostile tag crafted as a command option (leading `--...`) could still inject arguments. Reject anything that isn't a plain vX.Y.Z as soon as the tag enters computeIntegrationVersion(). Addresses a security-review finding on the release-flow PR.
chalin
force-pushed
the
chalin-m24-spec-release-flow-2026-0708
branch
from
July 9, 2026 14:58
098f0f1 to
619d328
Compare
Defense-in-depth on top of the vX.Y.Z validation in pick-branch: the quoting keeps the steps hygienic should the validation ever be loosened (e.g. to admit pre-release tags).
chalin
marked this pull request as ready for review
July 9, 2026 15:03
vitorvasc
approved these changes
Jul 9, 2026
otelbot-docs
Bot
removed
missing:docs-approval
otelbot-docs
Bot
added
the
ready-to-be-merged
chalin
added a commit
to chalin/opentelemetry.io
that referenced
this pull request
Jul 9, 2026
Dead arms since open-telemetry#10738 removed opentelemetry-specification and semantic-conventions from all-versions.sh: automation no longer calls this script for them, and a manual invocation would recreate the duplicate release PR that the specs-integration workflow now owns.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
scripts/gh/specs/create-or-finalize-pr.mjs(run with--helpfor usage).$GITHUB_ENV, and quotes$VERSION/$BRANCHin the workflow shell steps.