go/opentelemetry-go
1
0
Fork 0
mirror of https://github.com/open-telemetry/opentelemetry-go.git synced 2026-05-22 09:35:21 +02:00
Code Issues Releases Activity

Add doc on how to upgrade to new semconv (#7807)

Browse Source 
Adds a new "Semantic Conventions Upgrade" section to CONTRIBUTING.md
that documents the complete process for upgrading to newer semantic
conventions releases as requested in issue #7697.

It includes the details regarding:

- Generating new semconv packages
- Updating imports across the codebase
- Updating the opentelemetry-go-contrib linter configuration

---------

Co-authored-by: Damien Mathieu <42@dmathieu.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>
This commit is contained in:
João Correia
2026-03-09 15:20:53 +01:00
committed by GitHub
parent 4b025b4cf0
commit ba2747cd8c
1 changed files with 40 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
RELEASING.md
+40 -1
View File
@@ -4,7 +4,9 @@
Create a `Version Release` issue to track the release process.
## Semantic Convention Generation
## Semantic Convention Upgrade
### Semantic Convention Generation
New versions of the [OpenTelemetry Semantic Conventions] mean new versions of the `semconv` package need to be generated.
The `semconv-generate` make target is used for this.
@@ -22,6 +24,43 @@ make semconv-generate # Uses the exported TAG.
This should create a new sub-package of [`semconv`](./semconv).
Ensure things look correct before submitting a pull request to include the addition.
The `CHANGELOG.md` should also be updated to reflect the new changes:
```md
- The `go.opentelemetry.io/otel/semconv/<NEW VERSION>` package. The package contains semantic conventions from the `<NEW VERSION>` version of the OpenTelemetry Semantic Conventions. See the [migration documentation](./semconv/<NEW VERSION>/MIGRATION.md) for information on how to upgrade from `go.opentelemetry.io/otel/semconv/<PREVIOUS VERSION>`. (#PR_NUMBER)
```
> **Tip:** Change to the release and prior version to match the changes
### Update semconv imports
Once the new semconv module has been generated, update all semconv imports throughout the codebase to reference the new version:
```go
// Before
semconv "go.opentelemetry.io/otel/semconv/v1.37.0"
"go.opentelemetry.io/otel/semconv/v1.37.0/otelconv"
// After
semconv "go.opentelemetry.io/otel/semconv/v1.39.0"
"go.opentelemetry.io/otel/semconv/v1.39.0/otelconv"
```
Once complete, run `make` to check for any compilation or test failures.
#### Handling attribute changes
Some semconv releases might add new attributes or impact attributes that are currently being used. Changes could stem from a simple renaming, to more complex changes like merging attributes and property values being changed.
One should update the code to the new attributes that supersede the impacted ones, hence sticking to the semantic conventions. However, legacy attributes might still be emitted in accordance to the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable.
For an example on how such migration might have to be tracked and performed, see issue [#7806](https://github.com/open-telemetry/opentelemetry-go/issues/7806).
### Go contrib linter update
Update [.golangci.yml](https://github.com/open-telemetry/opentelemetry-go-contrib/blob/main/.golangci.yml) in [opentelemetry-go-contrib](https://github.com/open-telemetry/opentelemetry-go-contrib/) to mandate the new semconv version.
## Breaking changes validation
You can run `make gorelease` which runs [gorelease](https://pkg.go.dev/golang.org/x/exp/cmd/gorelease) to ensure that there are no unwanted changes made in the public API.