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. Checkout a local copy of the [OpenTelemetry Semantic Conventions] to the desired release tag.
92. Pull the latest `otel/semconvgen` image: `docker pull otel/semconvgen:latest`
103. Run the `make semconv-generate ...` target from this repository.
11
12For example,
13
14```sh
15export TAG="v1.21.0" # Change to the release version you are generating.
16export OTEL_SEMCONV_REPO="/absolute/path/to/opentelemetry/semantic-conventions"
17docker pull otel/semconvgen:latest
18make semconv-generate # Uses the exported TAG and OTEL_SEMCONV_REPO.
19```
20
21This should create a new sub-package of [`semconv`](./semconv).
22Ensure things look correct before submitting a pull request to include the addition.
23
24## Breaking changes validation
25
26You 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.
27
28You can check/report problems with `gorelease` [here](https://golang.org/issues/26420).
29
30## Pre-Release
31
32First, decide which module sets will be released and update their versions
33in `versions.yaml`. Commit this change to a new branch.
34
35Update go.mod for submodules to depend on the new release which will happen in the next step.
36
371. Run the `prerelease` make target. It creates a branch
38 `prerelease_<module set>_<new tag>` that will contain all release changes.
39
40 ```
41 make prerelease MODSET=<module set>
42 ```
43
442. Verify the changes.
45
46 ```
47 git diff ...prerelease_<module set>_<new tag>
48 ```
49
50 This should have changed the version for all modules to be `<new tag>`.
51 If these changes look correct, merge them into your pre-release branch:
52
53 ```go
54 git merge prerelease_<module set>_<new tag>
55 ```
56
573. Update the [Changelog](./CHANGELOG.md).
58 - Make sure all relevant changes for this release are included and are in language that non-contributors to the project can understand.
59 To verify this, you can look directly at the commits since the `<last tag>`.
60
61 ```
62 git --no-pager log --pretty=oneline "<last tag>..HEAD"
63 ```
64
65 - Move all the `Unreleased` changes into a new section following the title scheme (`[<new tag>] - <date of release>`).
66 - Update all the appropriate links at the bottom.
67
684. Push the changes to upstream and create a Pull Request on GitHub.
69 Be sure to include the curated changes from the [Changelog](./CHANGELOG.md) in the description.
70
71## Tag
72
73Once the Pull Request with all the version changes has been approved and merged it is time to tag the merged commit.
74
75***IMPORTANT***: It is critical you use the same tag that you used in the Pre-Release step!
76Failure to do so will leave things in a broken state. As long as you do not
77change `versions.yaml` between pre-release and this step, things should be fine.
78
79***IMPORTANT***: [There is currently no way to remove an incorrectly tagged version of a Go module](https://github.com/golang/go/issues/34189).
80It is critical you make sure the version you push upstream is correct.
81[Failure to do so will lead to minor emergencies and tough to work around](https://github.com/open-telemetry/opentelemetry-go/issues/331).
82
831. For each module set that will be released, run the `add-tags` make target
84 using the `<commit-hash>` of the commit on the main branch for the merged Pull Request.
85
86 ```
87 make add-tags MODSET=<module set> COMMIT=<commit hash>
88 ```
89
90 It should only be necessary to provide an explicit `COMMIT` value if the
91 current `HEAD` of your working directory is not the correct commit.
92
932. Push tags to the upstream remote (not your fork: `github.com/open-telemetry/opentelemetry-go.git`).
94 Make sure you push all sub-modules as well.
95
96 ```
97 git push upstream <new tag>
98 git push upstream <submodules-path/new tag>
99 ...
100 ```
101
102## Release
103
104Finally create a Release for the new `<new tag>` on GitHub.
105The release body should include all the release notes from the Changelog for this release.
106
107## Verify Examples
108
109After releasing verify that examples build outside of the repository.
110
111```
112./verify_examples.sh
113```
114
115The script copies examples into a different directory removes any `replace` declarations in `go.mod` and builds them.
116This ensures they build with the published release, not the local copy.
117
118## Post-Release
119
120### Contrib Repository
121
122Once 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.
123
124### Website Documentation
125
126Update the [Go instrumentation documentation] in the OpenTelemetry website under [content/en/docs/instrumentation/go].
127Importantly, bump any package versions referenced to be the latest one you just released and ensure all code examples still compile and are accurate.
128
129[OpenTelemetry Semantic Conventions]: https://github.com/open-telemetry/semantic-conventions
130[Go instrumentation documentation]: https://opentelemetry.io/docs/instrumentation/go/
131[content/en/docs/instrumentation/go]: https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/docs/instrumentation/go
132
133### Demo Repository
134
135Bump the dependencies in the following Go services:
136
137- [`accountingservice`](https://github.com/open-telemetry/opentelemetry-demo/tree/main/src/accountingservice)
138- [`checkoutservice`](https://github.com/open-telemetry/opentelemetry-demo/tree/main/src/checkoutservice)
139- [`productcatalogservice`](https://github.com/open-telemetry/opentelemetry-demo/tree/main/src/productcatalogservice)
View as plain text