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/CONTRIBUTING.md b/CONTRIBUTING.md index 1435db2e45..f156a5ac4c 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) @@ -300,6 +301,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. diff --git a/Makefile b/Makefile index f330c83b3d..df33d8e6aa 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,7 @@ SEMCONVGEN_VERSION=0.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 +103,12 @@ 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 $(LATEST_RELEASED_SEMCONV_VERSION) + .PHONY: schema-check schema-check: $(TOOLS_DIR)/schema_check.sh @@ -117,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"