[chore] Add backward-compatibility check to ci (#764)

.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:

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.

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"