You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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>
Copy file name to clipboardExpand all lines: RELEASING.md
+40-1Lines changed: 40 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,9 @@
4
4
5
5
Create a `Version Release` issue to track the release process.
6
6
7
-
## Semantic Convention Generation
7
+
## Semantic Convention Upgrade
8
+
9
+
### Semantic Convention Generation
8
10
9
11
New versions of the [OpenTelemetry Semantic Conventions] mean new versions of the `semconv` package need to be generated.
10
12
The `semconv-generate` make target is used for this.
@@ -22,6 +24,43 @@ make semconv-generate # Uses the exported TAG.
22
24
This should create a new sub-package of [`semconv`](./semconv).
23
25
Ensure things look correct before submitting a pull request to include the addition.
24
26
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/<NEWVERSION>/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:
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
+
25
64
## Breaking changes validation
26
65
27
66
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