Debian Codegraph @

RELEASING.md

raw
1 # Release Process
2
3 ## Create a `Version Release` issue
4
5 Create a `Version Release` issue to track the release process.
6
7 ## Semantic Convention Upgrade
8
9 ### Semantic Convention Generation
10
11 New versions of the [OpenTelemetry Semantic Conventions] mean new versions of the `semconv` package need to be generated.
12 The `semconv-generate` make target is used for this.
13
14 1. Set the `TAG` environment variable to the semantic convention tag you want to generate.
15 2. Run the `make semconv-generate ...` target from this repository.
16
17 For example,
18
19 ```sh
20 export TAG="v1.30.0" # Change to the release version you are generating.
21 make semconv-generate # Uses the exported TAG.
22 ```
23
24 This should create a new sub-package of [`semconv`](./semconv).
25 Ensure things look correct before submitting a pull request to include the addition.
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/<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
64 ## Breaking changes validation
65
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.
67
68 You can check/report problems with `gorelease` [here](https://golang.org/issues/26420).
69
70 ## Verify changes for contrib repository
71
72 If 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.
73
74 Follow [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.
75
76 ## Pre-Release
77
78 First, decide which module sets will be released and update their versions
79 in `versions.yaml`. Commit this change to a new branch.
80
81 Update go.mod for submodules to depend on the new release which will happen in the next step.
82
83 1. Run the `prerelease` make target. It creates a branch
84 `prerelease_<module set>_<new tag>` that will contain all release changes.
85
86 ```
87 make prerelease MODSET=<module set>
88 ```
89
90 2. Verify the changes.
91
92 ```
93 git diff ...prerelease_<module set>_<new tag>
94 ```
95
96 This should have changed the version for all modules to be `<new tag>`.
97 If these changes look correct, merge them into your pre-release branch:
98
99 ```go
100 git merge prerelease_<module set>_<new tag>
101 ```
102
103 3. Update the [Changelog](./CHANGELOG.md).
104 - Make sure all relevant changes for this release are included and are written in language that non-contributors to the project can understand.
105 To verify this, you can look directly at the commits since the `<last tag>`.
106
107 ```
108 git --no-pager log --pretty=oneline "<last tag>..HEAD"
109 ```
110
111 - Move all the `Unreleased` changes into a new section following the title scheme (`[<new tag>] - <date of release>`).
112 - 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.
113 - Update all the appropriate links at the bottom.
114
115 4. Push the changes to upstream and create a Pull Request on GitHub.
116 Be sure to include the curated changes from the [Changelog](./CHANGELOG.md) in the description.
117
118 ## Tag
119
120 Once the Pull Request with all the version changes has been approved and merged it is time to tag the merged commit.
121
122 ***IMPORTANT***: It is critical you use the same tag that you used in the Pre-Release step!
123 Failure to do so will leave things in a broken state. As long as you do not
124 change `versions.yaml` between pre-release and this step, things should be fine.
125
126 ***IMPORTANT***: [There is currently no way to remove an incorrectly tagged version of a Go module](https://github.com/golang/go/issues/34189).
127 It is critical you make sure the version you push upstream is correct.
128 [Failure to do so will lead to minor emergencies and tough to work around](https://github.com/open-telemetry/opentelemetry-go/issues/331).
129
130 1. For each module set that will be released, run the `add-tags` make target
131 using the `<commit-hash>` of the commit on the main branch for the merged Pull Request.
132
133 ```
134 make add-tags MODSET=<module set> COMMIT=<commit hash>
135 ```
136
137 It should only be necessary to provide an explicit `COMMIT` value if the
138 current `HEAD` of your working directory is not the correct commit.
139
140 2. Push tags to the upstream remote (not your fork: `github.com/open-telemetry/opentelemetry-go.git`).
141 Make sure you push all sub-modules as well.
142
143 ```
144 git push upstream <new tag>
145 git push upstream <submodules-path/new tag>
146 ...
147 ```
148
149 ## Sign artifacts
150
151 To ensure we comply with CNCF best practices, we need to sign the release artifacts.
152
153 Download the `.tar.gz` and `.zip` archives from the [tags page](https://github.com/open-telemetry/opentelemetry-go/tags) for the new release tag.
154 Both archives need to be signed with your GPG key.
155
156 You can use [this script] to verify the contents of the archives before signing them.
157
158 To find your GPG key ID, run:
159
160 ```terminal
161 gpg --list-secret-keys --keyid-format=long
162 ```
163
164 The key ID is the 16-character string after `sec rsa4096/` (or similar).
165
166 Set environment variables and sign both artifacts:
167
168 ```terminal
169 export VERSION="<version>" # e.g., v1.32.0
170 export KEY_ID="<your-gpg-key-id>"
171
172 gpg --local-user $KEY_ID --armor --detach-sign opentelemetry-go-$VERSION.tar.gz
173 gpg --local-user $KEY_ID --armor --detach-sign opentelemetry-go-$VERSION.zip
174 ```
175
176 You can verify the signatures with:
177
178 ```terminal
179 gpg --verify opentelemetry-go-$VERSION.tar.gz.asc opentelemetry-go-$VERSION.tar.gz
180 gpg --verify opentelemetry-go-$VERSION.zip.asc opentelemetry-go-$VERSION.zip
181 ```
182
183 [this script]: https://github.com/MrAlias/attest-sh
184
185 ## Release
186
187 Finally create a Release for the new `<new tag>` on GitHub.
188 The release body should include all the release notes from the Changelog for this release.
189
190 ***IMPORTANT***: GitHub Releases are immutable once created.
191 You must upload the signed artifacts (`.tar.gz`, `.tar.gz.asc`, `.zip`, and `.zip.asc`) when creating the release, as they cannot be added or modified later.
192
193 ## Post-Release
194
195 ### Contrib Repository
196
197 Once 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.
198
199 ### Website Documentation
200
201 Update the [Go instrumentation documentation] in the OpenTelemetry website under [content/en/docs/languages/go].
202 Importantly, bump any package versions referenced to be the latest one you just released and ensure all code examples still compile and are accurate.
203
204 [OpenTelemetry Semantic Conventions]: https://github.com/open-telemetry/semantic-conventions
205 [Go instrumentation documentation]: https://opentelemetry.io/docs/languages/go/
206 [content/en/docs/languages/go]: https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/docs/languages/go
207
208 ### Close the milestone
209
210 Once a release is made, ensure all issues that were fixed and PRs that were merged as part of this release are added to the corresponding milestone.
211 This helps track what changes were included in each release.
212
213 - To find issues that haven't been included in a milestone, use this [GitHub search query](https://github.com/open-telemetry/opentelemetry-go/issues?q=is%3Aissue%20no%3Amilestone%20is%3Aclosed%20sort%3Aupdated-desc%20reason%3Acompleted%20-label%3AStale%20linked%3Apr)
214 - To find merged PRs that haven't been included in a milestone, use this [GitHub search query](https://github.com/open-telemetry/opentelemetry-go/pulls?q=is%3Apr+no%3Amilestone+is%3Amerged).
215
216 Once all related issues and PRs have been added to the milestone, close the milestone.
217
218 ### Close the `Version Release` issue
219
220 Once the todo list in the `Version Release` issue is complete, close the issue.