1# How to Create a Release of OpenCensus Proto (for Maintainers Only) 2 3## Build Environments 4 5We re-generate gen-go files and deploy jars to Maven Central under the following systems: 6 7- Ubuntu 14.04 8 9Other systems may also work, but we haven't verified them. 10 11## Release Go files 12 13To generate the Go files from protos, you'll need to install protoc, protoc-gen-go and grpc-gateway plugins first. 14Follow the instructions [here](http://google.github.io/proto-lens/installing-protoc.html), 15[here](https://github.com/golang/protobuf#installation) and [here](https://github.com/grpc-ecosystem/grpc-gateway#installation). 16 17Then run the following commands to re-generate the gen-go files: 18 19```bash 20$ cd $(go env GOPATH)/src/github.com/census-instrumentation/opencensus-proto 21$ git checkout -b update-gen-go 22$ rm -rf gen-go 23$ cd src 24$ ./mkgogen.sh 25$ git add -A 26$ git commit -m "Update gen-go files." 27``` 28 29Go through PR review and merge the changes to GitHub. 30 31## Release Ruby files 32 33To generate the Ruby files from protos, you'll need to install grpc-tools gem. 34 35```bash 36gem install grpc-tools 37``` 38 39Then run the following commands to re-generate the gen-ruby files: 40 41```bash 42$ git@github.com:census-instrumentation/opencensus-proto.git 43$ cd opencensus-proto 44$ git checkout -b update-gen-ruby 45$ rm -rf gen-ruby 46$ cd src 47$ ./mkrubygen.sh 48$ git add -A 49$ git commit -m "Update gen-ruby files." 50``` 51 52## Release Python files 53 54To generate the Python files from protos, you'll need to install grpc-tools from PIP. 55 56```bash 57python -m pip install grpcio-tools 58``` 59 60Then run the following commands to re-generate the gen-python files: 61 62```bash 63$ git checkout -b update-gen-python # Assume you're under opencensus-proto/ 64$ cd src 65$ ./mkpygen.sh 66$ git add -A 67$ git commit -m "Update gen-python files." 68``` 69 70## Tagging the Release 71 72Our release branches follow the naming convention of `v<major>.<minor>.x`, while the tags include the 73patch version `v<major>.<minor>.<patch>`. For example, the same branch `v0.4.x` would be used to create 74all `v0.4` tags (e.g. `v0.4.0`, `v0.4.1`). 75 76In this section upstream repository refers to the main opencensus-proto github 77repository. 78 79Before any push to the upstream repository you need to create a [personal access 80token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). 81 821. Create the release branch and push it to GitHub: 83 84 ```bash 85 $ MAJOR=0 MINOR=4 PATCH=0 # Set appropriately for new release 86 $ JAVA_VERSION_FILES=(build.gradle) 87 $ PYTHON_VERSION_FILES=(gen-python/version.py) 88 $ git checkout -b v$MAJOR.$MINOR.x master 89 $ git push upstream v$MAJOR.$MINOR.x 90 ``` 91 922. Enable branch protection for the new branch, if you have admin access. 93 Otherwise, let someone with admin access know that there is a new release 94 branch. 95 96 - Open the branch protection settings for the new branch, by following 97 [Github's instructions](https://help.github.com/articles/configuring-protected-branches/). 98 - Copy the settings from a previous branch, i.e., check 99 - `Protect this branch` 100 - `Require pull request reviews before merging` 101 - `Require status checks to pass before merging` 102 - `Include administrators` 103 104 Enable the following required status checks: 105 - `cla/google` 106 - `continuous-integration/travis-ci` 107 - Uncheck everything else. 108 - Click "Save changes". 109 1103. For `master` branch: 111 112 - Change root build files to the next minor snapshot (e.g. 113 `0.5.0-SNAPSHOT`). 114 115 ```bash 116 $ git checkout -b bump-version master 117 # Change version to next minor (and keep -SNAPSHOT and .dev0) 118 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$((MINOR+1)).0'\1/' \ 119 "${JAVA_VERSION_FILES[@]}" 120 $ sed -i 's/[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$((MINOR+1))'\1/' \ 121 "${PYTHON_VERSION_FILES[@]}" 122 $ ./gradlew build 123 $ git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle" 124 ``` 125 126 - Go through PR review and push the master branch to GitHub: 127 128 ```bash 129 $ git checkout master 130 $ git merge --ff-only bump-version 131 $ git push upstream master 132 ``` 133 1344. For `vMajor.Minor.x` branch: 135 136 - Change root build files to remove "-SNAPSHOT" for the next release 137 version (e.g. `0.4.0`). Commit the result and make a tag: 138 139 ```bash 140 $ git checkout -b release v$MAJOR.$MINOR.x 141 # Change version to remove -SNAPSHOT and .dev0 142 $ sed -i 's/-SNAPSHOT\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/\1/' "${JAVA_VERSION_FILES[@]}" 143 $ sed -i 's/dev0\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'0'\1/' "${PYTHON_VERSION_FILES[@]}" 144 $ ./gradlew build 145 $ git commit -a -m "Bump version to $MAJOR.$MINOR.$PATCH" 146 $ git tag -a v$MAJOR.$MINOR.$PATCH -m "Version $MAJOR.$MINOR.$PATCH" 147 ``` 148 149 - Change root build files to the next snapshot version (e.g. 150 `0.4.1-SNAPSHOT`). Commit the result: 151 152 ```bash 153 # Change version to next patch and add -SNAPSHOT and .dev1 154 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT'\1/' \ 155 "${JAVA_VERSION_FILES[@]}" 156 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$MINOR.dev$((PATCH+1))'\1/' \ 157 "${PYTHON_VERSION_FILES[@]}" 158 $ ./gradlew build 159 $ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT" 160 ``` 161 162 - Go through PR review and push the release tag and updated release branch 163 to GitHub: 164 165 ```bash 166 $ git checkout v$MAJOR.$MINOR.x 167 $ git merge --ff-only release 168 $ git push upstream v$MAJOR.$MINOR.$PATCH 169 $ git push upstream v$MAJOR.$MINOR.x 170 ``` 171 172## Release Java Jar 173 174Deployment to Maven Central (or the snapshot repo) is for all of the artifacts 175from the project. 176 177### Prerequisites 178 179If you haven't done already, please follow the instructions 180[here](https://github.com/census-instrumentation/opencensus-java/blob/master/RELEASING.md#prerequisites) 181to set up the OSSRH (OSS Repository Hosting) account and signing keys. This is required for releasing 182to Maven Central. 183 184### Branch 185 186Before building/deploying, be sure to switch to the appropriate tag. The tag 187must reference a commit that has been pushed to the main repository, i.e., has 188gone through code review. For the current release use: 189 190```bash 191$ git checkout -b v$MAJOR.$MINOR.$PATCH tags/v$MAJOR.$MINOR.$PATCH 192``` 193 194### Initial Deployment 195 196The following command will build the whole project and upload it to Maven 197Central. Parallel building [is not safe during 198uploadArchives](https://issues.gradle.org/browse/GRADLE-3420). 199 200```bash 201$ ./gradlew clean build && ./gradlew -Dorg.gradle.parallel=false uploadArchives 202``` 203 204If the version has the `-SNAPSHOT` suffix, the artifacts will automatically go 205to the snapshot repository. Otherwise it's a release deployment and the 206artifacts will go to a staging repository. 207 208When deploying a Release, the deployment will create [a new staging 209repository](https://oss.sonatype.org/#stagingRepositories). You'll need to look 210up the ID in the OSSRH UI (usually in the form of `opencensus-*`). 211 212### Releasing on Maven Central 213 214Once all of the artifacts have been pushed to the staging repository, the 215repository must first be `closed`, which will trigger several sanity checks on 216the repository. If this completes successfully, the repository can then be 217`released`, which will begin the process of pushing the new artifacts to Maven 218Central (the staging repository will be destroyed in the process). You can see 219the complete process for releasing to Maven Central on the [OSSRH 220site](http://central.sonatype.org/pages/releasing-the-deployment.html). 221 222## Push Python package to PyPI 223 224We follow the same package distribution process outlined at 225[Python Packaging User Guide](https://packaging.python.org/tutorials/packaging-projects/). 226 227### Prerequisites 228 229If you haven't already, install the latest versions of setuptools, wheel and twine: 230```bash 231$ python3 -m pip install --user --upgrade setuptools wheel twine 232``` 233 234### Branch 235 236Before building/deploying, be sure to switch to the appropriate tag. The tag 237must reference a commit that has been pushed to the main repository, i.e., has 238gone through code review. For the current release use: 239 240```bash 241$ git checkout -b v$MAJOR.$MINOR.$PATCH tags/v$MAJOR.$MINOR.$PATCH 242``` 243 244### Generate and upload the distribution archives 245 246```bash 247$ cd gen-python 248$ python3 setup.py sdist bdist_wheel 249$ python3 -m twine upload dist/* 250``` 251 252## Announcement 253 254Once deployment is done, go to Github [release 255page](https://github.com/census-instrumentation/opencensus-proto/releases), press 256`Draft a new release` to write release notes about the new release. 257 258You can use `git log upstream/v$MAJOR.$((MINOR-1)).x..upstream/v$MAJOR.$MINOR.x --graph --first-parent` 259or the Github [compare tool](https://github.com/census-instrumentation/opencensus-proto/compare/) 260to view a summary of all commits since last release as a reference. 261 262Please pick major or important user-visible changes only. 263