From 70f78d308d4eeabb1ef87309024dcfc12f50710a Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 22 Feb 2024 12:35:38 -0800 Subject: [PATCH 1/7] Add backward-compatibility check to makefile --- .github/workflows/checks.yml | 7 +++++++ Makefile | 9 ++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index a4e32cba18..d7a284a688 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -91,6 +91,13 @@ jobs: - name: verify semantic convention tables run: make table-check + semantic-conventions-compatibility: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: verify semantic convention compatibility with latest released version + run: make compatibility-check + schemas-check: runs-on: ubuntu-latest steps: diff --git a/Makefile b/Makefile index f330c83b3d..c5968340b0 100644 --- a/Makefile +++ b/Makefile @@ -15,9 +15,11 @@ CHLOGGEN_CONFIG := .chloggen/config.yaml # Keep links in model/README.md and .vscode/settings.json in sync! SEMCONVGEN_VERSION=0.24.0 +LASTEST_RELEASED_SEMCONV_VERSION=1.24.0 + # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all -all: install-tools markdownlint markdown-link-check misspell table-check schema-check \ +all: install-tools markdownlint markdown-link-check misspell table-check compatibility-check schema-check \ check-file-and-folder-names-in-docs .PHONY: check-file-and-folder-names-in-docs @@ -103,6 +105,11 @@ table-check: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check +.PHONY: compatibility-check +compatibility-check: + docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ + otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source compatibility --previous-version ${LASTEST_RELEASED_SEMCONV_VERSION} --ignore-warnings + .PHONY: schema-check schema-check: $(TOOLS_DIR)/schema_check.sh From db0b715d62950a5d2dc0d056e4b689af8dc2ebef Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 4 Apr 2024 12:55:27 -0700 Subject: [PATCH 2/7] update contributing.md --- CONTRIBUTING.md | 18 +++++++++++++++++- Makefile | 2 +- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1435db2e45..f0ee6453ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -300,6 +300,18 @@ To check the validity of links in all markdown files, run the following command: make markdown-link-check ``` +### Version compatibility check + +Semantic conventions are validated for backward compatibility with last released versions. Here's [the full list of compatibility checks](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/README.md#version-compatibility-check). +Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead. +It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes. + +You can run backward compatibility check in all yaml files with the following command: + +```bash +make compatibility-check +``` + ## Updating the referenced specification version 1. Open the `./internal/tools/update_specification_version.sh` script. @@ -313,6 +325,7 @@ make markdown-link-check - Ensure the referenced specification version is up to date. Use [tooling to update the spec](#updating-the-referenced-specification-version) if needed. +- Update `LASTEST_RELEASED_SEMCONV_VERSION` in `Makefile` to the new version you're about to release. - 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}`. @@ -323,7 +336,10 @@ make markdown-link-check `.chloggen` folder automatically - Double check that `CHANGELOG.md` is updated with the proper `v{version}` - Send staging branch as PR for review. -- Create a tag `v{version}` on the merged PR and push remote. +- Create a tag v{version} on the merged PR and push remote. + +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 diff --git a/Makefile b/Makefile index c5968340b0..5b6c5def91 100644 --- a/Makefile +++ b/Makefile @@ -15,7 +15,7 @@ CHLOGGEN_CONFIG := .chloggen/config.yaml # Keep links in model/README.md and .vscode/settings.json in sync! SEMCONVGEN_VERSION=0.24.0 -LASTEST_RELEASED_SEMCONV_VERSION=1.24.0 +LASTEST_RELEASED_SEMCONV_VERSION=1.25.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all From 16ddb40917426cc6281061b60a5de3aa2338a88b Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 4 Apr 2024 12:57:24 -0700 Subject: [PATCH 3/7] update contributing.md --- CONTRIBUTING.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0ee6453ed..fedc771a7e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -338,9 +338,6 @@ make compatibility-check - Send staging branch as PR for review. - Create a tag v{version} on the merged PR and push remote. -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 From 3b4f369917506ccfbe1aaa2c9e4e32b9b9e40fba Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 4 Apr 2024 12:59:07 -0700 Subject: [PATCH 4/7] toc --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fedc771a7e..700add7a6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,7 @@ requirements and recommendations. - [Markdown style](#markdown-style) - [Misspell check](#misspell-check) - [Markdown link check](#markdown-link-check) + - [Version compatibility check](#version-compatibility-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) From f333d72aded84e8c3ec004e4bda0044209821051 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 4 Apr 2024 21:06:42 -0700 Subject: [PATCH 5/7] automate getting latest tag --- CONTRIBUTING.md | 1 - Makefile | 5 ++--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 700add7a6b..f58fa15e05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -326,7 +326,6 @@ make compatibility-check - Ensure the referenced specification version is up to date. Use [tooling to update the spec](#updating-the-referenced-specification-version) if needed. -- Update `LASTEST_RELEASED_SEMCONV_VERSION` in `Makefile` to the new version you're about to release. - 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}`. diff --git a/Makefile b/Makefile index 5b6c5def91..4e8250f399 100644 --- a/Makefile +++ b/Makefile @@ -15,8 +15,6 @@ CHLOGGEN_CONFIG := .chloggen/config.yaml # Keep links in model/README.md and .vscode/settings.json in sync! SEMCONVGEN_VERSION=0.24.0 -LASTEST_RELEASED_SEMCONV_VERSION=1.25.0 - # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all all: install-tools markdownlint markdown-link-check misspell table-check compatibility-check schema-check \ @@ -105,10 +103,11 @@ table-check: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check +LATEST_RELEASED_SEMCONV_VERSION := $(shell git describe --tags --abbrev=0 | sed 's/v//g') .PHONY: compatibility-check compatibility-check: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ - otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source compatibility --previous-version ${LASTEST_RELEASED_SEMCONV_VERSION} --ignore-warnings + otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source compatibility --previous-version $(LATEST_RELEASED_SEMCONV_VERSION) .PHONY: schema-check schema-check: From 3506dff210ce5901889f8daad6ca5d500ebee41a Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 4 Apr 2024 21:10:49 -0700 Subject: [PATCH 6/7] oops --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f58fa15e05..f156a5ac4c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -336,7 +336,7 @@ make compatibility-check `.chloggen` folder automatically - Double check that `CHANGELOG.md` is updated with the proper `v{version}` - Send staging branch as PR for review. -- Create a tag v{version} on the merged PR and push remote. +- Create a tag `v{version}` on the merged PR and push remote. ## Merging existing ECS conventions From f488896b445d8e691b0c1ee00188162c62a68dc1 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 5 Apr 2024 09:46:39 -0700 Subject: [PATCH 7/7] add to make check --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 4e8250f399..df33d8e6aa 100644 --- a/Makefile +++ b/Makefile @@ -123,7 +123,7 @@ fix-format: # Run all checks in order of speed / likely failure. .PHONY: check -check: misspell markdownlint check-format markdown-toc markdown-link-check +check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1) @echo "All checks complete"