1# How to Create a Release of OpenCensus Java (for Maintainers Only) 2 3## Build Environments 4 5We deploy OpenCensus Java 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## Prerequisites 12 13### Setup OSSRH and Signing 14 15If you haven't deployed artifacts to Maven Central before, you need to setup 16your OSSRH (OSS Repository Hosting) account and signing keys. 17 18- Follow the instructions on [this 19 page](http://central.sonatype.org/pages/ossrh-guide.html) to set up an 20 account with OSSRH. 21 - You only need to create the account, not set up a new project 22 - Contact a OpenCensus Java maintainer to add your account after you 23 have created it. 24- (For release deployment only) [Install 25 GnuPG](http://central.sonatype.org/pages/working-with-pgp-signatures.html#installing-gnupg) 26 and [generate your key 27 pair](http://central.sonatype.org/pages/working-with-pgp-signatures.html#generating-a-key-pair). 28 You'll also need to [publish your public 29 key](http://central.sonatype.org/pages/working-with-pgp-signatures.html#distributing-your-public-key) 30 to make it visible to the Sonatype servers. 31- Put your GnuPG key password and OSSRH account information in 32 `<your-home-directory>/.gradle/gradle.properties`: 33 34 ``` 35 # You need the signing properties only if you are making release deployment 36 signing.keyId=<8-character-public-key-id> 37 signing.password=<key-password> 38 signing.secretKeyRingFile=<your-home-directory>/.gnupg/secring.gpg 39 40 ossrhUsername=<ossrh-username> 41 ossrhPassword=<ossrh-password> 42 checkstyle.ignoreFailures=false 43 ``` 44 45## Tagging the Release 46 47The first step in the release process is to create a release branch, bump 48versions, and create a tag for the release. Our release branches follow the 49naming convention of `v<major>.<minor>.x`, while the tags include the patch 50version `v<major>.<minor>.<patch>`. For example, the same branch `v0.4.x` would 51be used to create all `v0.4` tags (e.g. `v0.4.0`, `v0.4.1`). 52 53In this section upstream repository refers to the main opencensus-java github 54repository. 55 56Before any push to the upstream repository you need to create a [personal access 57token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). 58 591. Create the release branch and push it to GitHub: 60 61 ```bash 62 $ MAJOR=0 MINOR=4 PATCH=0 # Set appropriately for new release 63 $ VERSION_FILES=( 64 build.gradle 65 examples/build.gradle 66 examples/pom.xml 67 api/src/main/java/io/opencensus/common/OpenCensusLibraryInformation.java 68 exporters/metrics/ocagent/src/main/java/io/opencensus/exporter/metrics/ocagent/OcAgentNodeUtils.java 69 exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentNodeUtils.java 70 examples/spring/servlet/build.gradle 71 examples/spring/servlet/pom.xml 72 ) 73 $ git checkout -b v$MAJOR.$MINOR.x master 74 $ git push upstream v$MAJOR.$MINOR.x 75 ``` 76 The branch will be automatically protected by the GitHub branch protection rule for release 77 branches. 78 792. For `master` branch: 80 81 - Change root build files to the next minor snapshot (e.g. 82 `0.5.0-SNAPSHOT`). 83 84 ```bash 85 $ git checkout -b bump-version master 86 # Change version to next minor (and keep -SNAPSHOT) 87 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_VERSION\)/'$MAJOR.$((MINOR+1)).0'\1/' \ 88 "${VERSION_FILES[@]}" 89 $ ./gradlew build 90 $ git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle" 91 ``` 92 93 - Go through PR review and push the master branch to GitHub: 94 95 ```bash 96 $ git checkout master 97 $ git merge --ff-only bump-version 98 $ git push upstream master 99 ``` 100 1013. For `vMajor.Minor.x` branch: 102 103 - Change root build files to remove "-SNAPSHOT" for the next release 104 version (e.g. `0.4.0`). Commit the result and make a tag: 105 106 ```bash 107 $ git checkout -b release v$MAJOR.$MINOR.x 108 # Change version to remove -SNAPSHOT 109 $ sed -i 's/-SNAPSHOT\(.*CURRENT_OPENCENSUS_VERSION\)/\1/' "${VERSION_FILES[@]}" 110 $ ./gradlew build 111 $ git commit -a -m "Bump version to $MAJOR.$MINOR.$PATCH" 112 $ git tag -a v$MAJOR.$MINOR.$PATCH -m "Version $MAJOR.$MINOR.$PATCH" 113 ``` 114 115 - Change root build files to the next snapshot version (e.g. 116 `0.4.1-SNAPSHOT`). Commit the result: 117 118 ```bash 119 # Change version to next patch and add -SNAPSHOT 120 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_VERSION\)/'$MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT'\1/' \ 121 "${VERSION_FILES[@]}" 122 $ ./gradlew build 123 $ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT" 124 ``` 125 126 - Go through PR review and push the release tag and updated release branch 127 to GitHub (note: do not squash the commits when you merge otherwise you 128 will lose the release tag): 129 130 ```bash 131 $ git checkout v$MAJOR.$MINOR.x 132 $ git merge --ff-only release 133 $ git push upstream v$MAJOR.$MINOR.$PATCH 134 $ git push upstream v$MAJOR.$MINOR.x 135 ``` 136 137## Deployment 138 139Deployment to Maven Central (or the snapshot repo) is for all of the artifacts 140from the project. 141 142### Branch 143 144Before building/deploying, be sure to switch to the appropriate tag. The tag 145must reference a commit that has been pushed to the main repository, i.e., has 146gone through code review. For the current release use: 147 148```bash 149$ git checkout -b v$MAJOR.$MINOR.$PATCH tags/v$MAJOR.$MINOR.$PATCH 150``` 151 152### Building and Deploying 153 154The following command will build the whole project and upload it to Maven 155Central. Parallel building [is not safe during 156uploadArchives](https://issues.gradle.org/browse/GRADLE-3420). 157 158```bash 159$ ./gradlew clean build && ./gradlew -Dorg.gradle.parallel=false uploadArchives 160``` 161 162If the version has the `-SNAPSHOT` suffix, the artifacts will automatically go 163to the snapshot repository. Otherwise it's a release deployment and the 164artifacts will go to a staging repository. 165 166When deploying a Release, the deployment will create [a new staging 167repository](https://oss.sonatype.org/#stagingRepositories). You'll need to look 168up the ID in the OSSRH UI (usually in the form of `opencensus-*`). 169 170## Releasing on Maven Central 171 172Once all of the artifacts have been pushed to the staging repository, the 173repository must first be `closed`, which will trigger several sanity checks on 174the repository. If this completes successfully, the repository can then be 175`released`, which will begin the process of pushing the new artifacts to Maven 176Central (the staging repository will be destroyed in the process). You can see 177the complete process for releasing to Maven Central on the [OSSRH 178site](http://central.sonatype.org/pages/releasing-the-deployment.html). 179 180## Announcement 181 182Once deployment is done, go to Github [release 183page](https://github.com/census-instrumentation/opencensus-java/releases), press 184`Draft a new release` to write release notes about the new release. 185 186You can use `git log upstream/v$MAJOR.$((MINOR-1)).x..upstream/v$MAJOR.$MINOR.x --graph --first-parent` 187or the Github [compare tool](https://github.com/census-instrumentation/opencensus-java/compare/) 188to view a summary of all commits since last release as a reference. In addition, you can refer to 189[CHANGELOG.md](https://github.com/census-instrumentation/opencensus-java/blob/master/CHANGELOG.md) 190for a list of major changes since last release. 191 192Please pick major or important user-visible changes only. 193 194## Update release versions in documentations and build files 195 196After releasing is done, you need to update all readmes and examples to point to the 197latest version. 198 1991. Update README.md and gradle/maven build files on `master` branch: 200 201```bash 202$ git checkout -b bump-document-version master 203$ BUILD_FILES=( 204 examples/build.gradle 205 examples/pom.xml 206 ) 207$ README_FILES=( 208 README.md 209 contrib/appengine_standard_util/README.md 210 contrib/dropwizard/README.md 211 contrib/dropwizard5/README.md 212 contrib/exemplar_util/README.md 213 contrib/grpc_util/README.md 214 contrib/http_jaxrs/README.md 215 contrib/http_jetty_client/README.md 216 contrib/http_servlet/README.md 217 contrib/http_util/README.md 218 contrib/log_correlation/log4j2/README.md 219 contrib/log_correlation/stackdriver/README.md 220 contrib/spring/README.md 221 contrib/spring_sleuth_v1x/README.md 222 contrib/zpages/README.md 223 exporters/stats/prometheus/README.md 224 exporters/stats/signalfx/README.md 225 exporters/stats/stackdriver/README.md 226 exporters/trace/datadog/README.md 227 exporters/trace/elasticsearch/README.md 228 exporters/trace/instana/README.md 229 exporters/trace/logging/README.md 230 exporters/trace/jaeger/README.md 231 exporters/trace/ocagent/README.md 232 exporters/trace/stackdriver/README.md 233 exporters/trace/zipkin/README.md 234 ) 235# Substitute versions in build files 236$ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*LATEST_OPENCENSUS_RELEASE_VERSION\)/'$MAJOR.$MINOR.$PATCH'\1/' \ 237 "${BUILD_FILES[@]}" 238# Substitute versions in build.gradle examples in README.md 239$ sed -i 's/\(\(compile\|runtime\).\+io\.opencensus:.\+:\)[0-9]\+\.[0-9]\+\.[0-9]\+/\1'$MAJOR.$MINOR.$PATCH'/' \ 240 "${README_FILES[@]}" 241# Substitute versions in maven pom examples in README.md 242$ sed -i 's/\(<version>\)[0-9]\+\.[0-9]\+\.[0-9]\+/\1'$MAJOR.$MINOR.$PATCH'/' \ 243 "${README_FILES[@]}" 244$ git commit -a -m "Update release versions for all readme and build files." 245``` 246 2472. Go through PR review and merge it to GitHub master branch. 248 2493. In addition, create a PR to mark the new release in 250[CHANGELOG.md](https://github.com/census-instrumentation/opencensus-java/blob/master/CHANGELOG.md) 251on master branch. Once that PR is merged, cherry-pick the commit and create another PR to the 252release branch (branch v$MAJOR.$MINOR.x). 253 254## Patch Release 255All patch releases should include only bug-fixes, and must avoid adding/modifying the public APIs. 256To cherry-pick one commit use the following command: 257```bash 258$ COMMIT=1224f0a # Set the right commit hash. 259$ git cherry-pick -x $COMMIT 260``` 261 262## Known Issues 263 264### Deployment for tag v0.5.0 265To rebuild the releases on the tag v0.5.0 use: 266```bash 267$ ./gradlew clean build && ./gradlew uploadArchives 268``` 269 270If option `-Dorg.gradle.parallel=false` is used, you will hit [this bug](https://issues.sonatype.org/browse/OSSRH-19485) 271caused by [this bug](https://github.com/gradle/gradle/issues/1827) in gradle 3.5. 272