From f249173193c50bb985cd59116f76e753ed21f392 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 05:11:38 -0800 Subject: [PATCH 1/5] Add clarification about `OTEL_SEMCONV_STABILITY_OPT_IN` (#1758) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/non-normative/db-migration.md | 4 ++++ docs/non-normative/http-migration.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index 596a665a2c..bd6d2039bd 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -22,6 +22,10 @@ updated to the stable database semantic conventions, they: - May drop the environment variable in their next major version and emit only the stable database conventions. +> [!NOTE] +> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating +> from an experimental semantic convention to its initial stable version. + ## Summary of changes This section summarizes the changes made to the HTTP semantic conventions diff --git a/docs/non-normative/http-migration.md b/docs/non-normative/http-migration.md index d0c70fe68f..959648b76c 100644 --- a/docs/non-normative/http-migration.md +++ b/docs/non-normative/http-migration.md @@ -29,6 +29,10 @@ updated to the stable HTTP semantic conventions, they: - May drop the environment variable in their next major version and emit only the stable HTTP and networking conventions. +> [!NOTE] +> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating +> from an experimental semantic convention to its initial stable version. + ## Summary of changes This section summarizes the changes made to the HTTP semantic conventions From eae7a310558039380b3bbc15f28e3e606028df9a Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 05:13:29 -0800 Subject: [PATCH 2/5] Fix link (#1761) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/general/recording-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md index 91246b7247..ea5189eadc 100644 --- a/docs/general/recording-errors.md +++ b/docs/general/recording-errors.md @@ -61,7 +61,7 @@ When the operation ends with an error, instrumentation: When the operation fails with an exception, the span status description SHOULD be set to the exception message. -Refer to the [recording exceptions](#recording-errors) on capturing exception +Refer to the [recording exceptions](#recording-exceptions) on capturing exception details. ## Recording errors on metrics From b810141201bb6b9b6e1c4e038f4d9d878056777d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 08:48:07 -0800 Subject: [PATCH 3/5] Move release instructions to RELEASING.md (#1762) --- CONTRIBUTING.md | 28 ---------------------------- RELEASING.md | 26 ++++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 28 deletions(-) create mode 100644 RELEASING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68755d1cf2..e2b4b153e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,6 @@ requirements and recommendations. - [Update the tables of content](#update-the-tables-of-content) - [Markdown link check](#markdown-link-check) - [Updating the referenced specification version](#updating-the-referenced-specification-version) -- [Making a Release](#making-a-release) - [Merging existing ECS conventions](#merging-existing-ecs-conventions) @@ -415,33 +414,6 @@ make markdown-link-check 4. Run the script from the root directory, e.g. `semantic-conventions$ ./internal/tools/update_specification_version.sh`. 5. Add all modified files to the change submit and submit a PR. -## Making a Release - -- Ensure the referenced specification version is up to date. Use - [tooling to update the spec](#updating-the-referenced-specification-version) - if needed. -- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) - against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any. -- Create a staging branch for the release. - - Update `schema-next.yaml` file and move to `schemas/{version}` - - Ensure the `next` version is appropriately configured as the `{version}`. - - Copy `schema-next.yaml` to `schemas/{version}`. - - Add `next` as a version in `schema-next.yaml` version. - - Run `make chlog-update VERSION=v{version}` - - `make chlog-update` will clean up all the current `.yaml` files inside the - `.chloggen` folder automatically - - Double check that `CHANGELOG.md` is updated with the proper `v{version}` - - Send staging branch as PR for review. -- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): - - Set title and tag to `v{version}` - - Set target to the commit of the merged release PR - - Copy changelog to the release notes - - Verify that the release looks like expected - - Publish release - -New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR) -eventually results in new version of schema file being published. - ## Merging existing ECS conventions The Elastic Common Schema (ECS) is being merged into OpenTelemetry Semantic diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000000..18f54b3347 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,26 @@ +# Making a Release + +- Ensure the referenced specification version is up to date. Use + [tooling to update the spec](./CONTRIBUTING.md#updating-the-referenced-specification-version) + if needed. +- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) + against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any. +- Create a staging branch for the release. + - Update `schema-next.yaml` file and move to `schemas/{version}` + - Ensure the `next` version is appropriately configured as the `{version}`. + - Copy `schema-next.yaml` to `schemas/{version}`. + - Add `next` as a version in `schema-next.yaml` version. + - Run `make chlog-update VERSION=v{version}` + - `make chlog-update` will clean up all the current `.yaml` files inside the + `.chloggen` folder automatically + - Double check that `CHANGELOG.md` is updated with the proper `v{version}` + - Send staging branch as PR for review. +- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): + - Set title and tag to `v{version}` + - Set target to the commit of the merged release PR + - Copy changelog to the release notes + - Verify that the release looks like expected + - Publish release + +New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR) +eventually results in new version of schema file being published. From 77f0b70d36c42f072ee1391afd681774cea4e39c Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 10:20:16 -0800 Subject: [PATCH 4/5] Release automation (#1765) Co-authored-by: Liudmila Molkova --- .github/workflows/prepare-release.yml | 59 +++++++++++++++++++ .../scripts/use-cla-approved-github-bot.sh | 4 ++ 2 files changed, 63 insertions(+) create mode 100644 .github/workflows/prepare-release.yml create mode 100755 .github/workflows/scripts/use-cla-approved-github-bot.sh diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/prepare-release.yml new file mode 100644 index 0000000000..f53766c277 --- /dev/null +++ b/.github/workflows/prepare-release.yml @@ -0,0 +1,59 @@ +name: Prepare release +on: + workflow_dispatch: + inputs: + version: + description: 'The version to release, e.g. 1.30.0' + required: true + +jobs: + create-pull-request: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate version + run: | + version=${{ inputs.version }} + if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "unexpected version: $version" + exit 1 + fi + + - name: Use CLA approved github bot + run: .github/workflows/scripts/use-cla-approved-github-bot.sh + + - name: Update schema files + run: | + if ! grep -q "^ next:$" schema-next.yaml; then + echo "String 'next:' not found in the file" + exit 1 + fi + + version=${{ inputs.version }} + sed -i "0,/^ next:$/s// $version:/" schema-next.yaml + cp schema-next.yaml "schemas/$version" + git add "schemas/$version" + + sed -i "0,/^ $version:$/s// next:\n $version:/" schema-next.yaml + + - name: Update change log + run: | + make chlog-update VERSION=v${{ inputs.version }} + + - name: Create pull request + env: + # not using secrets.GITHUB_TOKEN since pull requests from that token do not run workflows + GH_TOKEN: ${{ secrets.OPENTELEMETRYBOT_GITHUB_TOKEN }} + run: | + version=${{ inputs.version }} + message="Prepare release v${version}" + body="Prepare release \`v${version}\`." + branch="opentelemetrybot/prepare-release-v${version}" + + git checkout -b $branch + git commit -a -m "$message" + git push --set-upstream origin $branch + gh pr create --title "$message" \ + --body "$body" \ + --base main diff --git a/.github/workflows/scripts/use-cla-approved-github-bot.sh b/.github/workflows/scripts/use-cla-approved-github-bot.sh new file mode 100755 index 0000000000..a4c68b0e30 --- /dev/null +++ b/.github/workflows/scripts/use-cla-approved-github-bot.sh @@ -0,0 +1,4 @@ +#!/bin/bash -e + +git config user.name opentelemetrybot +git config user.email 107717825+opentelemetrybot@users.noreply.github.com From 0e109d266238cbd2ca5025f54edd51d5f18019b3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 20 Jan 2025 13:56:50 -0800 Subject: [PATCH 5/5] Label all new issues with `triage:needs-triage` label (#1767) --- .github/ISSUE_TEMPLATE/bug_report.yaml | 2 +- .github/ISSUE_TEMPLATE/change_proposal.yaml | 2 +- .github/ISSUE_TEMPLATE/new-conventions.yaml | 2 +- .../workflows/scripts/prepare-new-issue.sh | 29 +++++++------------ 4 files changed, 14 insertions(+), 21 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 43a6c3c748..252669d92b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -1,6 +1,6 @@ name: Bug report description: Create a report to help us improve -labels: ["bug", "triage:needs-triage"] +labels: ["bug"] body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index bb0d28736a..6eab59ae69 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -1,6 +1,6 @@ name: Propose changes to existing conventions description: Propose changes you'd like to be added to existing conventions -labels: ["enhancement", "triage:needs-triage"] +labels: ["enhancement"] body: - type: dropdown id: area diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index eb43279195..f4e3498651 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -1,6 +1,6 @@ name: Propose new semantic conventions description: Propose new conventions you'd like to be part of the OpenTelemetry project -labels: ["enhancement", "triage:needs-triage", "experts needed"] +labels: ["enhancement", "experts needed"] body: - type: markdown attributes: diff --git a/.github/workflows/scripts/prepare-new-issue.sh b/.github/workflows/scripts/prepare-new-issue.sh index 6142e5b3b8..391fc698ab 100755 --- a/.github/workflows/scripts/prepare-new-issue.sh +++ b/.github/workflows/scripts/prepare-new-issue.sh @@ -28,7 +28,7 @@ if [[ -z "${ISSUE:-}" || -z "${BODY:-}" || -z "${OPENER:-}" ]]; then exit 0 fi -LABELS="" +LABELS="triage:needs-triage" AREAS_SECTION_START=$( (echo "${BODY}" | grep -n '### Area(s)' | awk '{ print $1 }' | grep -oE '[0-9]+') || echo '-1' ) BODY_AREAS="" @@ -45,26 +45,19 @@ for AREA in ${BODY_AREAS}; do continue fi - if [[ -n "${LABELS}" ]]; then - LABELS+="," - fi - LABELS+="${AREA}" + LABELS+=",${AREA}" done -if [[ -v PINGED_AREAS[@] ]]; then - echo "The issue was associated with areas:" "${!PINGED_AREAS[@]}" +if [[ -v BODY_AREAS[@] ]]; then + echo "The issue was associated with areas:" "${!BODY_AREAS[@]}" else echo "No related areas were given" fi -if [[ -n "${LABELS}" ]]; then - # Notes on this call: - # 1. Labels will be deduplicated by the GitHub CLI. - # 2. The call to edit the issue will fail if any of the - # labels doesn't exist. We can be reasonably sure that - # all labels will exist since they come from a known set. - echo "Adding the following labels: ${LABELS//,/ /}" - gh issue edit "${ISSUE}" --add-label "${LABELS}" || true -else - echo "No labels were found to add" -fi +# Notes on this call: +# 1. Labels will be deduplicated by the GitHub CLI. +# 2. The call to edit the issue will fail if any of the +# labels doesn't exist. We can be reasonably sure that +# all labels will exist since they come from a known set. +echo "Adding the following labels: ${LABELS//,/ /}" +gh issue edit "${ISSUE}" --add-label "${LABELS}" || true