1# Release Process
2
3## Semantic Convention Generation
4
5New versions of the [OpenTelemetry Semantic Conventions] mean new versions of the `semconv` package need to be generated.
6The `semconv-generate` make target is used for this.
7
81. Set the `TAG` environment variable to the semantic convention tag you want to generate.
92. Run the `make semconv-generate ...` target from this repository.
10
11For example,
12
13```sh
14export TAG="v1.30.0" # Change to the release version you are generating.
15make semconv-generate # Uses the exported TAG.
16```
17
18This should create a new sub-package of [`semconv`](./semconv).
19Ensure things look correct before submitting a pull request to include the addition.
20
21## Breaking changes validation
22
23You can run `make gorelease` that runs [gorelease](https://pkg.go.dev/golang.org/x/exp/cmd/gorelease) to ensure that there are no unwanted changes done in the public API.
24
25You can check/report problems with `gorelease` [here](https://golang.org/issues/26420).
26
27## Verify changes for contrib repository
28
29If the changes in the main repository are going to affect the contrib repository, it is important to verify that the changes are compatible with the contrib repository.
30
31Follow [the steps](https://github.com/open-telemetry/opentelemetry-go-contrib/blob/main/RELEASING.md#verify-otel-changes) in the contrib repository to verify OTel changes.
32
33## Pre-Release
34
35First, decide which module sets will be released and update their versions
36in `versions.yaml`. Commit this change to a new branch.
37
38Update go.mod for submodules to depend on the new release which will happen in the next step.
39
401. Run the `prerelease` make target. It creates a branch
41 `prerelease_<module set>_<new tag>` that will contain all release changes.
42
43 ```
44 make prerelease MODSET=<module set>
45 ```
46
472. Verify the changes.
48
49 ```
50 git diff ...prerelease_<module set>_<new tag>
51 ```
52
53 This should have changed the version for all modules to be `<new tag>`.
54 If these changes look correct, merge them into your pre-release branch:
55
56 ```go
57 git merge prerelease_<module set>_<new tag>
58 ```
59
603. Update the [Changelog](./CHANGELOG.md).
61 - Make sure all relevant changes for this release are included and are in language that non-contributors to the project can understand.
62 To verify this, you can look directly at the commits since the `<last tag>`.
63
64 ```
65 git --no-pager log --pretty=oneline "<last tag>..HEAD"
66 ```
67
68 - Move all the `Unreleased` changes into a new section following the title scheme (`[<new tag>] - <date of release>`).
69 - Make sure the new section is under the comment for released section, like `<!-- Released section -->`, so it is protected from being overwritten in the future.
70 - Update all the appropriate links at the bottom.
71
724. Push the changes to upstream and create a Pull Request on GitHub.
73 Be sure to include the curated changes from the [Changelog](./CHANGELOG.md) in the description.
74
75## Tag
76
77Once the Pull Request with all the version changes has been approved and merged it is time to tag the merged commit.
78
79***IMPORTANT***: It is critical you use the same tag that you used in the Pre-Release step!
80Failure to do so will leave things in a broken state. As long as you do not
81change `versions.yaml` between pre-release and this step, things should be fine.
82
83***IMPORTANT***: [There is currently no way to remove an incorrectly tagged version of a Go module](https://github.com/golang/go/issues/34189).
84It is critical you make sure the version you push upstream is correct.
85[Failure to do so will lead to minor emergencies and tough to work around](https://github.com/open-telemetry/opentelemetry-go/issues/331).
86
871. For each module set that will be released, run the `add-tags` make target
88 using the `<commit-hash>` of the commit on the main branch for the merged Pull Request.
89
90 ```
91 make add-tags MODSET=<module set> COMMIT=<commit hash>
92 ```
93
94 It should only be necessary to provide an explicit `COMMIT` value if the
95 current `HEAD` of your working directory is not the correct commit.
96
972. Push tags to the upstream remote (not your fork: `github.com/open-telemetry/opentelemetry-go.git`).
98 Make sure you push all sub-modules as well.
99
100 ```
101 git push upstream <new tag>
102 git push upstream <submodules-path/new tag>
103 ...
104 ```
105
106## Release
107
108Finally create a Release for the new `<new tag>` on GitHub.
109The release body should include all the release notes from the Changelog for this release.
110
111## Post-Release
112
113### Contrib Repository
114
115Once verified be sure to [make a release for the `contrib` repository](https://github.com/open-telemetry/opentelemetry-go-contrib/blob/main/RELEASING.md) that uses this release.
116
117### Website Documentation
118
119Update the [Go instrumentation documentation] in the OpenTelemetry website under [content/en/docs/languages/go].
120Importantly, bump any package versions referenced to be the latest one you just released and ensure all code examples still compile and are accurate.
121
122[OpenTelemetry Semantic Conventions]: https://github.com/open-telemetry/semantic-conventions
123[Go instrumentation documentation]: https://opentelemetry.io/docs/languages/go/
124[content/en/docs/languages/go]: https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/docs/languages/go
125
126### Demo Repository
127
128Bump the dependencies in the following Go services:
129
130- [`accounting`](https://github.com/open-telemetry/opentelemetry-demo/tree/main/src/accounting)
131- [`checkoutservice`](https://github.com/open-telemetry/opentelemetry-demo/tree/main/src/checkout)
132- [`productcatalogservice`](https://github.com/open-telemetry/opentelemetry-demo/tree/main/src/product-catalog)