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