Skip to content
41 changes: 40 additions & 1 deletion RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down
Loading