You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
190 lines
6.8 KiB
190 lines
6.8 KiB
# How to Create a Release of OpenCensus Proto (for Maintainers Only) |
|
|
|
## Build Environments |
|
|
|
We re-generate gen-go files and deploy jars to Maven Central under the following systems: |
|
|
|
- Ubuntu 14.04 |
|
|
|
Other systems may also work, but we haven't verified them. |
|
|
|
## Release Go files |
|
|
|
To generate the Go files from protos, you'll need to install protoc, protoc-gen-go and grpc-gateway plugins first. |
|
Follow the instructions [here](http://google.github.io/proto-lens/installing-protoc.html), |
|
[here](https://github.com/golang/protobuf#installation) and [here](https://github.com/grpc-ecosystem/grpc-gateway#installation). |
|
|
|
Then run the following commands to re-generate the gen-go files: |
|
|
|
```bash |
|
$ cd $(go env GOPATH)/src/github.com/census-instrumentation/opencensus-proto |
|
$ git checkout -b update-gen-go |
|
$ rm -rf gen-go |
|
$ cd src |
|
$ ./mkgogen.sh |
|
$ git add -A |
|
$ git commit -m "Update gen-go files." |
|
``` |
|
|
|
Go through PR review and merge the changes to GitHub. |
|
|
|
## Tagging the Release |
|
|
|
Our release branches follow the naming convention of `v<major>.<minor>.x`, while the tags include the |
|
patch version `v<major>.<minor>.<patch>`. For example, the same branch `v0.4.x` would be used to create |
|
all `v0.4` tags (e.g. `v0.4.0`, `v0.4.1`). |
|
|
|
In this section upstream repository refers to the main opencensus-proto github |
|
repository. |
|
|
|
Before any push to the upstream repository you need to create a [personal access |
|
token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). |
|
|
|
1. Create the release branch and push it to GitHub: |
|
|
|
```bash |
|
$ MAJOR=0 MINOR=4 PATCH=0 # Set appropriately for new release |
|
$ VERSION_FILES=( |
|
build.gradle |
|
pom.xml |
|
) |
|
$ git checkout -b v$MAJOR.$MINOR.x master |
|
$ git push upstream v$MAJOR.$MINOR.x |
|
``` |
|
|
|
2. Enable branch protection for the new branch, if you have admin access. |
|
Otherwise, let someone with admin access know that there is a new release |
|
branch. |
|
|
|
- Open the branch protection settings for the new branch, by following |
|
[Github's instructions](https://help.github.com/articles/configuring-protected-branches/). |
|
- Copy the settings from a previous branch, i.e., check |
|
- `Protect this branch` |
|
- `Require pull request reviews before merging` |
|
- `Require status checks to pass before merging` |
|
- `Include administrators` |
|
|
|
Enable the following required status checks: |
|
- `cla/google` |
|
- `continuous-integration/travis-ci` |
|
- Uncheck everything else. |
|
- Click "Save changes". |
|
|
|
3. For `master` branch: |
|
|
|
- Change root build files to the next minor snapshot (e.g. |
|
`0.5.0-SNAPSHOT`). |
|
|
|
```bash |
|
$ git checkout -b bump-version master |
|
# Change version to next minor (and keep -SNAPSHOT) |
|
$ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$((MINOR+1)).0'\1/' \ |
|
"${VERSION_FILES[@]}" |
|
$ ./gradlew build |
|
$ git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle" |
|
``` |
|
|
|
- Go through PR review and push the master branch to GitHub: |
|
|
|
```bash |
|
$ git checkout master |
|
$ git merge --ff-only bump-version |
|
$ git push upstream master |
|
``` |
|
|
|
4. For `vMajor.Minor.x` branch: |
|
|
|
- Change root build files to remove "-SNAPSHOT" for the next release |
|
version (e.g. `0.4.0`). Commit the result and make a tag: |
|
|
|
```bash |
|
$ git checkout -b release v$MAJOR.$MINOR.x |
|
# Change version to remove -SNAPSHOT |
|
$ sed -i 's/-SNAPSHOT\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/\1/' "${VERSION_FILES[@]}" |
|
$ ./gradlew build |
|
$ git commit -a -m "Bump version to $MAJOR.$MINOR.$PATCH" |
|
$ git tag -a v$MAJOR.$MINOR.$PATCH -m "Version $MAJOR.$MINOR.$PATCH" |
|
``` |
|
|
|
- Change root build files to the next snapshot version (e.g. |
|
`0.4.1-SNAPSHOT`). Commit the result: |
|
|
|
```bash |
|
# Change version to next patch and add -SNAPSHOT |
|
$ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT'\1/' \ |
|
"${VERSION_FILES[@]}" |
|
$ ./gradlew build |
|
$ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT" |
|
``` |
|
|
|
- Go through PR review and push the release tag and updated release branch |
|
to GitHub: |
|
|
|
```bash |
|
$ git checkout v$MAJOR.$MINOR.x |
|
$ git merge --ff-only release |
|
$ git push upstream v$MAJOR.$MINOR.$PATCH |
|
$ git push upstream v$MAJOR.$MINOR.x |
|
``` |
|
|
|
## Release Java Jar |
|
|
|
Deployment to Maven Central (or the snapshot repo) is for all of the artifacts |
|
from the project. |
|
|
|
### Prerequisites |
|
|
|
If you haven't done already, please follow the instructions |
|
[here](https://github.com/census-instrumentation/opencensus-java/blob/master/RELEASING.md#prerequisites) |
|
to set up the OSSRH (OSS Repository Hosting) account and signing keys. This is required for releasing |
|
to Maven Central. |
|
|
|
### Branch |
|
|
|
Before building/deploying, be sure to switch to the appropriate tag. The tag |
|
must reference a commit that has been pushed to the main repository, i.e., has |
|
gone through code review. For the current release use: |
|
|
|
```bash |
|
$ git checkout -b v$MAJOR.$MINOR.$PATCH tags/v$MAJOR.$MINOR.$PATCH |
|
``` |
|
|
|
### Initial Deployment |
|
|
|
The following command will build the whole project and upload it to Maven |
|
Central. Parallel building [is not safe during |
|
uploadArchives](https://issues.gradle.org/browse/GRADLE-3420). |
|
|
|
```bash |
|
$ ./gradlew clean build && ./gradlew -Dorg.gradle.parallel=false uploadArchives |
|
``` |
|
|
|
If the version has the `-SNAPSHOT` suffix, the artifacts will automatically go |
|
to the snapshot repository. Otherwise it's a release deployment and the |
|
artifacts will go to a staging repository. |
|
|
|
When deploying a Release, the deployment will create [a new staging |
|
repository](https://oss.sonatype.org/#stagingRepositories). You'll need to look |
|
up the ID in the OSSRH UI (usually in the form of `opencensus-*`). |
|
|
|
### Releasing on Maven Central |
|
|
|
Once all of the artifacts have been pushed to the staging repository, the |
|
repository must first be `closed`, which will trigger several sanity checks on |
|
the repository. If this completes successfully, the repository can then be |
|
`released`, which will begin the process of pushing the new artifacts to Maven |
|
Central (the staging repository will be destroyed in the process). You can see |
|
the complete process for releasing to Maven Central on the [OSSRH |
|
site](http://central.sonatype.org/pages/releasing-the-deployment.html). |
|
|
|
## Announcement |
|
|
|
Once deployment is done, go to Github [release |
|
page](https://github.com/census-instrumentation/opencensus-proto/releases), press |
|
`Draft a new release` to write release notes about the new release. |
|
|
|
You can use `git log upstream/v$MAJOR.$((MINOR-1)).x..upstream/v$MAJOR.$MINOR.x --graph --first-parent` |
|
or the Github [compare tool](https://github.com/census-instrumentation/opencensus-proto/compare/) |
|
to view a summary of all commits since last release as a reference. |
|
|
|
Please pick major or important user-visible changes only.
|
|
|