Skip to content

Commit b050e55

Browse files
committed
Merge remote-tracking branch 'origin/main' into otelbot/spec-integration-v1.56.0-dev
2 parents 05e4df4 + 26a8285 commit b050e55

File tree

12 files changed

+1194
-60
lines changed

12 files changed

+1194
-60
lines changed

.github/workflows/update-semconv-integration-branch.yml

Lines changed: 17 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@ on:
88

99
permissions:
1010
contents: read
11+
# Needed so the "Pick integration branch" step can open a tracking issue
12+
# via gh when it detects problems (e.g. stale integration branches).
13+
issues: write
14+
15+
env:
16+
REPO: semantic-conventions
17+
# Abbreviation of REPO used in branch and submodule names
18+
ABBR: semconv
1119

1220
jobs:
1321
update-semconv-integration-branch:
@@ -28,34 +36,10 @@ jobs:
2836
# this is needed to trigger workflows when pushing new commits to an existing PR
2937
token: ${{ steps.otelbot-token.outputs.token }}
3038

31-
- name: Set environment variables
39+
- name: Pick integration branch
3240
env:
3341
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
34-
run: |
35-
branch_prefix="otelbot/semconv-integration"
36-
37-
version=$(git branch -r \
38-
| grep -E "^ *origin/$branch_prefix-v[0-9]+\.[0-9]+\..*-dev" \
39-
| sed "s|^ *origin/$branch_prefix-||" \
40-
| sed "s|-dev$||")
41-
42-
if [[ -z "$version" ]]; then
43-
latest_version=$(gh release view \
44-
--repo open-telemetry/semantic-conventions \
45-
--json tagName \
46-
--jq .tagName)
47-
if [[ $latest_version =~ ^v([0-9]+)\.([0-9]+)\. ]]; then
48-
major="${BASH_REMATCH[1]}"
49-
minor="${BASH_REMATCH[2]}"
50-
version="v$major.$((minor + 1)).0"
51-
else
52-
echo "unexpected version: $latest_version"
53-
exit 1
54-
fi
55-
fi
56-
57-
echo "VERSION=$version" >> $GITHUB_ENV
58-
echo "BRANCH=$branch_prefix-$version-dev" >> $GITHUB_ENV
42+
run: node scripts/gh/specs/pick-branch/cli.mjs --spec=semconv
5943

6044
- name: Checkout or create branch
6145
run: |
@@ -82,8 +66,8 @@ jobs:
8266
8367
- name: Update submodule and Hugo mounts
8468
run: |
85-
git submodule update --init content-modules/semantic-conventions
86-
cd content-modules/semantic-conventions
69+
git submodule update --init content-modules/${{ env.REPO }}
70+
cd content-modules/${{ env.REPO }}
8771
8872
if git ls-remote --exit-code --tags origin $VERSION; then
8973
git reset --hard $VERSION
@@ -95,18 +79,18 @@ jobs:
9579
commit_desc=$(git describe --tags)
9680
cd ../..
9781
98-
sed -i "s/^\tsemconv-pin = .*/\tsemconv-pin = $commit_desc/" .gitmodules
82+
sed -i "s/^\t${{ env.ABBR }}-pin = .*/\t${{ env.ABBR }}-pin = $commit_desc/" .gitmodules
9983
10084
if [ "$tag_exists" == "true" ]; then
101-
sed -i "s/^\(\s *\)semconv: .*/\1semconv: ${commit_desc#v}/" scripts/content-modules/adjust-pages.pl
85+
sed -i "s/^\(\s *\)${{ env.ABBR }}: .*/\1${{ env.ABBR }}: ${commit_desc#v}/" scripts/content-modules/adjust-pages.pl
10286
fi
10387
10488
./scripts/update-semconv-mounts.pl
10589
10690
git add -A
10791
10892
if ! git diff-index --quiet --cached HEAD; then
109-
git commit -am "Update semconv submodule to $commit_desc"
93+
git commit -am "Update ${{ env.ABBR }} submodule to $commit_desc"
11094
git push
11195
fi
11296
@@ -136,7 +120,7 @@ jobs:
136120
run: |
137121
prs=$(gh pr list --state open --head $BRANCH)
138122
if [ -z "$prs" ]; then
139-
gh pr create --title "DRAFT Update semantic conventions to unreleased $VERSION-dev" \
140-
--body "This is a draft PR used for identifying issues integrating the latest (unreleased) semantic conventions." \
123+
gh pr create --title "DRAFT Update ${{ env.REPO }} to unreleased $VERSION-dev" \
124+
--body "This is a draft PR used for identifying issues integrating the latest (unreleased) [${{ env.REPO }}](https://github.com/open-telemetry/${{ env.REPO }})." \
141125
--draft
142126
fi

.github/workflows/update-spec-integration-branch.yml

Lines changed: 5 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ on:
88

99
permissions:
1010
contents: read
11+
# Needed so the "Pick integration branch" step can open a tracking issue
12+
# via gh when it detects problems (e.g. stale integration branches).
13+
issues: write
1114

1215
env:
1316
REPO: opentelemetry-specification
@@ -32,34 +35,10 @@ jobs:
3235
fetch-depth: 0
3336
token: ${{ steps.otelbot-token.outputs.token }}
3437

35-
- name: Set environment variables
38+
- name: Pick integration branch
3639
env:
3740
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
38-
run: |
39-
branch_prefix="otelbot/${{ env.ABBR }}-integration"
40-
41-
version=$(git branch -r \
42-
| grep -E "^ *origin/$branch_prefix-v[0-9]+\.[0-9]+\..*-dev" \
43-
| sed "s|^ *origin/$branch_prefix-||" \
44-
| sed "s|-dev$||")
45-
46-
if [[ -z "$version" ]]; then
47-
latest_version=$(gh release view \
48-
--repo open-telemetry/${{ env.REPO }} \
49-
--json tagName \
50-
--jq .tagName)
51-
if [[ $latest_version =~ ^v([0-9]+)\.([0-9]+)\. ]]; then
52-
major="${BASH_REMATCH[1]}"
53-
minor="${BASH_REMATCH[2]}"
54-
version="v$major.$((minor + 1)).0"
55-
else
56-
echo "unexpected version: $latest_version"
57-
exit 1
58-
fi
59-
fi
60-
61-
echo "VERSION=$version" >> $GITHUB_ENV
62-
echo "BRANCH=$branch_prefix-$version-dev" >> $GITHUB_ENV
41+
run: node scripts/gh/specs/pick-branch/cli.mjs --spec=otel
6342

6443
- name: Checkout or create branch
6544
run: |

content/en/docs/contributing/pr-checks.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Pull request checks and tests
3+
linkTitle: PR checks & tests
34
description: Learn how to make your pull request successfully pass all checks
45
weight: 40
56
---

content/en/docs/contributing/sig-practices.md

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -221,7 +221,7 @@ PRs with changes to translations should aim for two approvals: one by a docs
221221
approver and one by a translation approver. Similar practices apply as suggested
222222
for the co-owned PRs.
223223

224-
### Merging PRs
224+
## Merging PRs
225225

226226
The following workflow can be applied by maintainers to merge PRs:
227227

@@ -233,3 +233,50 @@ The following workflow can be applied by maintainers to merge PRs:
233233
```shell
234234
export PR=<ID OF THE PR>; gh pr checks ${PR} --watch && gh pr merge ${PR} --squash
235235
```
236+
237+
## Specification PRs and integration branches {#spec-integration-branches}
238+
239+
The website continuously integrates unreleased changes from the
240+
[opentelemetry-specification][] and [semantic-conventions][] repositories. Two
241+
scheduled workflows ([details][ci-section]) run daily and keep a draft
242+
"integration" PR current with the next dev version:
243+
244+
- Branch pattern: `otelbot/spec-integration-vX.Y.Z-dev` and
245+
`otelbot/semconv-integration-vX.Y.Z-dev`.
246+
- List of live branches: [spec][spec-branches] · [semconv][semconv-branches].
247+
248+
[opentelemetry-specification]:
249+
https://github.com/open-telemetry/opentelemetry-specification
250+
[semantic-conventions]: https://github.com/open-telemetry/semantic-conventions
251+
[ci-section]: /site/build/ci-workflows/#spec-integration-branches
252+
[spec-branches]:
253+
https://github.com/open-telemetry/opentelemetry.io/branches/all?query=spec-integration
254+
[semconv-branches]:
255+
https://github.com/open-telemetry/opentelemetry.io/branches/all?query=semconv-integration
256+
257+
### Spec / semconv SIG maintainers
258+
259+
Just before cutting a release:
260+
261+
1. Find the latest integration branch for your spec at the links given in the
262+
previous section (e.g. `otelbot/spec-integration-v1.56.0-dev`).
263+
2. Open the associated PR (linked from the branch page).
264+
3. Trigger a fresh run of the corresponding workflow to pick up your latest
265+
changes:
266+
- [update-spec-integration-branch.yml][]
267+
- [update-semconv-integration-branch.yml][]
268+
4. If the PR checks are green, the spec is safe to release. If not, ping
269+
`@open-telemetry/docs-maintainers` so we can address breakage before the
270+
release goes out.
271+
272+
### Comms SIG maintainers
273+
274+
Throughout the month, regularly check the integration PRs and commit incremental
275+
fixes to keep their CI checks green. Catching breakage early — while the
276+
upstream change set is still small — is much easier than firefighting on release
277+
day.
278+
279+
[update-spec-integration-branch.yml]:
280+
https://github.com/open-telemetry/opentelemetry.io/actions/workflows/update-spec-integration-branch.yml
281+
[update-semconv-integration-branch.yml]:
282+
https://github.com/open-telemetry/opentelemetry.io/actions/workflows/update-semconv-integration-branch.yml

content/en/site/build/ci-workflows.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,59 @@ nothing needed to be committed.
263263
[pr-actions]:
264264
https://github.com/open-telemetry/opentelemetry.io/blob/main/.github/workflows/pr-actions.yml
265265

266+
## Spec integration branches {#spec-integration-branches}
267+
268+
Two scheduled workflows track unreleased changes from upstream spec repositories
269+
and keep a draft PR ("integration branch") current with the next development
270+
version:
271+
272+
| Workflow file | Upstream repository | Branch slug |
273+
| ----------------------------------------- | ----------------------------- | ----------- |
274+
| [update-spec-integration-branch.yml][] | `opentelemetry-specification` | `spec` |
275+
| [update-semconv-integration-branch.yml][] | `semantic-conventions` | `semconv` |
276+
277+
[update-spec-integration-branch.yml]:
278+
https://github.com/open-telemetry/opentelemetry.io/blob/main/.github/workflows/update-spec-integration-branch.yml
279+
[update-semconv-integration-branch.yml]:
280+
https://github.com/open-telemetry/opentelemetry.io/blob/main/.github/workflows/update-semconv-integration-branch.yml
281+
282+
Both workflows delegate the "pick the next version + branch" step to a shared
283+
Node helper, [scripts/gh/specs/pick-branch/cli.mjs][]. The helper:
284+
285+
- Reuses an existing `otelbot/<slug>-integration-vX.Y.Z-dev` branch when one
286+
exists and the version has not yet been released; otherwise bumps the latest
287+
release tag's minor version.
288+
- Writes `VERSION` and `BRANCH` to `$GITHUB_ENV` for downstream steps.
289+
- Opens a tracking issue (label `<slug>-integration-warning`, deduplicated) when
290+
it detects problems such as multiple stale integration branches.
291+
292+
[scripts/gh/specs/pick-branch/cli.mjs]:
293+
https://github.com/open-telemetry/opentelemetry.io/tree/main/scripts/gh/specs/pick-branch
294+
295+
### Run modes
296+
297+
The helper auto-selects between dry-run and write mode and prints a `[mode]`
298+
banner explaining its choice:
299+
300+
| Context | Default behavior | Override |
301+
| --------------------- | ---------------- | ------------------- |
302+
| GitHub Actions | write | pass `--dry-run` |
303+
| Local (anywhere else) | dry-run | pass `--no-dry-run` |
304+
305+
Locally, dry-run still runs all read-only `git`/`gh` commands (so the issue
306+
deduplication check executes), but skips writes. With `--no-dry-run` the helper
307+
uses your local `gh` credentials; if `GITHUB_ENV` is unset, `VERSION`/`BRANCH`
308+
are printed to stdout only. Try it:
309+
310+
```sh
311+
node scripts/gh/specs/pick-branch/cli.mjs --spec=otel
312+
node scripts/gh/specs/pick-branch/cli.mjs --spec=semconv --no-dry-run
313+
node scripts/gh/specs/pick-branch/cli.mjs --help
314+
```
315+
316+
Pure logic and CLI argument parsing live in `index.mjs` and are covered by
317+
`*.test.mjs` files in the same folder (`npm run test:local-tools` to run them).
318+
266319
## Other workflows
267320

268321
The repository includes several other workflows:
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import { describe, test } from 'node:test';
2+
import assert from 'node:assert/strict';
3+
4+
import { parseCliArgs, cliUsage } from './index.mjs';
5+
6+
describe('pick-branch: CLI args', () => {
7+
test('defaults: spec=otel, dry-run on when not in Actions', () => {
8+
const result = parseCliArgs([], {});
9+
assert.equal(result.spec, 'otel');
10+
assert.equal(result.dryRun, true);
11+
assert.equal(result.help, false);
12+
assert.match(result.dryRunReason, /GITHUB_ACTIONS/);
13+
});
14+
15+
test('default dry-run is OFF when GITHUB_ACTIONS=true', () => {
16+
const result = parseCliArgs([], { GITHUB_ACTIONS: 'true' });
17+
assert.equal(result.dryRun, false);
18+
assert.equal(result.dryRunReason, 'GITHUB_ACTIONS=true');
19+
});
20+
21+
test('default dry-run is ON when GITHUB_ACTIONS is set to anything else', () => {
22+
assert.equal(parseCliArgs([], { GITHUB_ACTIONS: 'false' }).dryRun, true);
23+
assert.equal(parseCliArgs([], { GITHUB_ACTIONS: '' }).dryRun, true);
24+
});
25+
26+
test('--dry-run forces dry-run even under Actions', () => {
27+
const result = parseCliArgs(['--dry-run'], { GITHUB_ACTIONS: 'true' });
28+
assert.equal(result.dryRun, true);
29+
assert.equal(result.dryRunReason, '--dry-run flag');
30+
});
31+
32+
test('--no-dry-run forces writes even outside Actions', () => {
33+
const result = parseCliArgs(['--no-dry-run'], {});
34+
assert.equal(result.dryRun, false);
35+
assert.equal(result.dryRunReason, '--no-dry-run flag');
36+
});
37+
38+
test('later --dry-run / --no-dry-run wins', () => {
39+
assert.equal(parseCliArgs(['--no-dry-run', '--dry-run'], {}).dryRun, true);
40+
assert.equal(parseCliArgs(['--dry-run', '--no-dry-run'], {}).dryRun, false);
41+
});
42+
43+
test('--spec=<id> selects a known spec', () => {
44+
assert.equal(parseCliArgs(['--spec=semconv'], {}).spec, 'semconv');
45+
});
46+
47+
test('--spec <id> (separate token) selects a known spec', () => {
48+
assert.equal(parseCliArgs(['--spec', 'semconv'], {}).spec, 'semconv');
49+
});
50+
51+
test('-s <id> short form selects a known spec', () => {
52+
assert.equal(parseCliArgs(['-s', 'semconv'], {}).spec, 'semconv');
53+
});
54+
55+
test('--help sets help flag without throwing', () => {
56+
const result = parseCliArgs(['--help'], {});
57+
assert.equal(result.help, true);
58+
});
59+
60+
test('-h short form sets help flag', () => {
61+
assert.equal(parseCliArgs(['-h'], {}).help, true);
62+
});
63+
64+
test('unknown --spec value throws', () => {
65+
assert.throws(() => parseCliArgs(['--spec=bogus'], {}), /Unknown --spec/);
66+
});
67+
68+
test('unknown flag throws', () => {
69+
assert.throws(() => parseCliArgs(['--bogus'], {}), /Unknown argument/);
70+
});
71+
72+
test('--spec without value throws', () => {
73+
assert.throws(() => parseCliArgs(['--spec'], {}), /Missing value/);
74+
});
75+
76+
test('cliUsage mentions both specs and the dry-run flags', () => {
77+
const text = cliUsage();
78+
assert.match(text, /otel\|semconv/);
79+
assert.match(text, /--dry-run/);
80+
assert.match(text, /--no-dry-run/);
81+
});
82+
});

0 commit comments

Comments
 (0)