Skip to content

Commit ba2747c

Browse files
jmmcorreiadmathieupellared
authored
Add doc on how to upgrade to new semconv (open-telemetry#7807)
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 open-telemetry#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>
1 parent 4b025b4 commit ba2747c

1 file changed

Lines changed: 40 additions & 1 deletion

File tree

RELEASING.md

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44

55
Create a `Version Release` issue to track the release process.
66

7-
## Semantic Convention Generation
7+
## Semantic Convention Upgrade
8+
9+
### Semantic Convention Generation
810

911
New versions of the [OpenTelemetry Semantic Conventions] mean new versions of the `semconv` package need to be generated.
1012
The `semconv-generate` make target is used for this.
@@ -22,6 +24,43 @@ make semconv-generate # Uses the exported TAG.
2224
This should create a new sub-package of [`semconv`](./semconv).
2325
Ensure things look correct before submitting a pull request to include the addition.
2426

27+
The `CHANGELOG.md` should also be updated to reflect the new changes:
28+
29+
```md
30+
- 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)
31+
```
32+
33+
> **Tip:** Change to the release and prior version to match the changes
34+
35+
### Update semconv imports
36+
37+
Once the new semconv module has been generated, update all semconv imports throughout the codebase to reference the new version:
38+
39+
```go
40+
// Before
41+
semconv "go.opentelemetry.io/otel/semconv/v1.37.0"
42+
"go.opentelemetry.io/otel/semconv/v1.37.0/otelconv"
43+
44+
45+
// After
46+
semconv "go.opentelemetry.io/otel/semconv/v1.39.0"
47+
"go.opentelemetry.io/otel/semconv/v1.39.0/otelconv"
48+
```
49+
50+
Once complete, run `make` to check for any compilation or test failures.
51+
52+
#### Handling attribute changes
53+
54+
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.
55+
56+
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.
57+
58+
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).
59+
60+
### Go contrib linter update
61+
62+
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.
63+
2564
## Breaking changes validation
2665

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

0 commit comments

Comments
 (0)