Skip to content

Commit

Permalink
Update release documentation (open-telemetry#993)
Browse files Browse the repository at this point in the history
* Update release docs

Clean up language and include directions to handle the Changelog during
a release.

* Fix grammar
  • Loading branch information
MrAlias authored Jul 31, 2020
1 parent b74edd4 commit 423183e
Showing 1 changed file with 36 additions and 19 deletions.
55 changes: 36 additions & 19 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
# Release Process

## Pre-Release
Update go.mod for submodules to depend on the new release which will happen
in the next step. This will create build failure for those who depend
on the master branch instead or released version. But they shouldn't be
depending on the master. So it is not a concern.

1. Run the pre-release script. It creates a branch pre_release_<tag> to make the changes.
Update go.mod for submodules to depend on the new release which will happen in the next step.

1. Run the pre-release script. It creates a branch `pre_release_<new tag>` that will contain all release changes.

```
./pre_release.sh -t <new tag>
Expand All @@ -18,26 +16,42 @@ depending on the master. So it is not a concern.
git diff master
```
3. Push the changes to upstream.
This should have changed the version for all modules to be `<new tag>`.
```
git push
```
3. Update the [Changelog](./CHANGELOG.md).
- Make sure all relevant changes for this release are included and are in language that non-contributors to the project can understand.
To verify this, you can look directly at the commits since the `<last tag>`.
```
git --no-pager log --pretty=oneline "<last tag>..HEAD"
```
- Move all the `Unreleased` changes into a new section following the title scheme (`[<new tag>] - <date of release>`).
- Update all the appropriate links at the bottom.
4. Create a PR on github and merge the PR once approved.
4. Push the changes to upstream and create a Pull Request on GitHub.
Be sure to include the curated changes from the [Changelog](./CHANGELOG.md) in the description.
## Tag
Now create a new Tag on the commit hash of the changes made in pre-release step.
Use the same tag as used in the pre-release step.
1. Run the tag.sh script.
Once the Pull Request with all the version changes has been approved and merged it is time to tag the merged commit.
***IMPORTANT***: It is critical you use the same tag that you used in the Pre-Release step!
Failure to do so will leave things in a broken state.
***IMPORTANT***: [There is currently no way to remove an incorrectly tagged version of a Go module](https://github.com/golang/go/issues/34189).
It is critical you make sure the version you push upstream is correct.
[Failure to do so will lead to minor emergencies and tough to work around](https://github.com/open-telemetry/opentelemetry-go/issues/331).
1. Run the tag.sh script using the `<commit-hash>` of the commit on the master branch for the merged Pull Request.
```
./tag.sh <new tag> <commit-hash>
```
2. Push tags upstream. Make sure you run this for all sub-modules as well.
2. Push tags to the upstream remote (not your fork: `github.com/open-telemetry/opentelemetry-go.git`).
Make sure you push all sub-modules as well.
```
git push upstream <new tag>
Expand All @@ -46,15 +60,18 @@ Use the same tag as used in the pre-release step.
```
## Release
Now create a release for the new `<new tag>` on github.
The release body should include all the release notes in the Changelog for this release.
Additionally, the `tag.sh` script generates commit logs since last release which can be used to suppliment the release notes.
Finally create a Release for the new `<new tag>` on GitHub.
The release body should include all the release notes from the Changelog for this release.
Additionally, the `tag.sh` script generates commit logs since last release which can be used to supplement the release notes.
## Verify Examples
After releasing run following script to verify that examples build outside of the otel repo.
The script copies examples into a different directory and builds them.
After releasing verify that examples build outside of the repository.
```
./verify_examples.sh
```
The script copies examples into a different directory removes any `replace` declarations in `go.mod` and builds them.
This ensures they build with the published release, not the local copy.

0 comments on commit 423183e

Please sign in to comment.