Home | History | Annotate | Download | only in opencensus-java 
      1 # How to Create a Release of OpenCensus Java (for Maintainers Only)
      2 
      3 ## Build Environments
      4 
      5 We deploy OpenCensus Java to Maven Central under the following systems:
      6 
      7 -   Ubuntu 14.04
      8 
      9 Other systems may also work, but we haven't verified them.
     10 
     11 ## Prerequisites
     12 
     13 ### Setup OSSRH and Signing
     14 
     15 If you haven't deployed artifacts to Maven Central before, you need to setup
     16 your 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 
     47 The first step in the release process is to create a release branch, bump
     48 versions, and create a tag for the release. Our release branches follow the
     49 naming convention of `v<major>.<minor>.x`, while the tags include the patch
     50 version `v<major>.<minor>.<patch>`. For example, the same branch `v0.4.x` would
     51 be used to create all `v0.4` tags (e.g. `v0.4.0`, `v0.4.1`).
     52 
     53 In this section upstream repository refers to the main opencensus-java github
     54 repository.
     55 
     56 Before any push to the upstream repository you need to create a [personal access
     57 token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).
     58 
     59 1.  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/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentNodeUtils.java
     69       )
     70     $ git checkout -b v$MAJOR.$MINOR.x master
     71     $ git push upstream v$MAJOR.$MINOR.x
     72     ```
     73     The branch will be automatically protected by the GitHub branch protection rule for release
     74     branches.
     75 
     76 2.  For `master` branch:
     77 
     78     -   Change root build files to the next minor snapshot (e.g.
     79         `0.5.0-SNAPSHOT`).
     80 
     81     ```bash
     82     $ git checkout -b bump-version master
     83     # Change version to next minor (and keep -SNAPSHOT)
     84     $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_VERSION\)/'$MAJOR.$((MINOR+1)).0'\1/' \
     85       "${VERSION_FILES[@]}"
     86     $ ./gradlew build
     87     $ git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle"
     88     ```
     89 
     90     -   Go through PR review and push the master branch to GitHub:
     91 
     92     ```bash
     93     $ git checkout master
     94     $ git merge --ff-only bump-version
     95     $ git push upstream master
     96     ```
     97 
     98 3.  For `vMajor.Minor.x` branch:
     99 
    100     -   Change root build files to remove "-SNAPSHOT" for the next release
    101         version (e.g. `0.4.0`). Commit the result and make a tag:
    102 
    103     ```bash
    104     $ git checkout -b release v$MAJOR.$MINOR.x
    105     # Change version to remove -SNAPSHOT
    106     $ sed -i 's/-SNAPSHOT\(.*CURRENT_OPENCENSUS_VERSION\)/\1/' "${VERSION_FILES[@]}"
    107     $ ./gradlew build
    108     $ git commit -a -m "Bump version to $MAJOR.$MINOR.$PATCH"
    109     $ git tag -a v$MAJOR.$MINOR.$PATCH -m "Version $MAJOR.$MINOR.$PATCH"
    110     ```
    111 
    112     -   Change root build files to the next snapshot version (e.g.
    113         `0.4.1-SNAPSHOT`). Commit the result:
    114 
    115     ```bash
    116     # Change version to next patch and add -SNAPSHOT
    117     $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_VERSION\)/'$MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT'\1/' \
    118      "${VERSION_FILES[@]}"
    119     $ ./gradlew build
    120     $ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT"
    121     ```
    122 
    123     -   Go through PR review and push the release tag and updated release branch
    124         to GitHub:
    125 
    126     ```bash
    127     $ git checkout v$MAJOR.$MINOR.x
    128     $ git merge --ff-only release
    129     $ git push upstream v$MAJOR.$MINOR.$PATCH
    130     $ git push upstream v$MAJOR.$MINOR.x
    131     ```
    132 
    133 ## Deployment
    134 
    135 Deployment to Maven Central (or the snapshot repo) is for all of the artifacts
    136 from the project.
    137 
    138 ### Branch
    139 
    140 Before building/deploying, be sure to switch to the appropriate tag. The tag
    141 must reference a commit that has been pushed to the main repository, i.e., has
    142 gone through code review. For the current release use:
    143 
    144 ```bash
    145 $ git checkout -b v$MAJOR.$MINOR.$PATCH tags/v$MAJOR.$MINOR.$PATCH
    146 ```
    147 
    148 ### Initial Deployment
    149 
    150 The following command will build the whole project and upload it to Maven
    151 Central. Parallel building [is not safe during
    152 uploadArchives](https://issues.gradle.org/browse/GRADLE-3420).
    153 
    154 ```bash
    155 $ ./gradlew clean build && ./gradlew -Dorg.gradle.parallel=false uploadArchives
    156 ```
    157 
    158 If the version has the `-SNAPSHOT` suffix, the artifacts will automatically go
    159 to the snapshot repository. Otherwise it's a release deployment and the
    160 artifacts will go to a staging repository.
    161 
    162 When deploying a Release, the deployment will create [a new staging
    163 repository](https://oss.sonatype.org/#stagingRepositories). You'll need to look
    164 up the ID in the OSSRH UI (usually in the form of `opencensus-*`).
    165 
    166 ## Releasing on Maven Central
    167 
    168 Once all of the artifacts have been pushed to the staging repository, the
    169 repository must first be `closed`, which will trigger several sanity checks on
    170 the repository. If this completes successfully, the repository can then be
    171 `released`, which will begin the process of pushing the new artifacts to Maven
    172 Central (the staging repository will be destroyed in the process). You can see
    173 the complete process for releasing to Maven Central on the [OSSRH
    174 site](http://central.sonatype.org/pages/releasing-the-deployment.html).
    175 
    176 ## Announcement
    177 
    178 Once deployment is done, go to Github [release
    179 page](https://github.com/census-instrumentation/opencensus-java/releases), press
    180 `Draft a new release` to write release notes about the new release.
    181 
    182 You can use `git log upstream/v$MAJOR.$((MINOR-1)).x..upstream/v$MAJOR.$MINOR.x --graph --first-parent`
    183 or the Github [compare tool](https://github.com/census-instrumentation/opencensus-java/compare/)
    184 to view a summary of all commits since last release as a reference. In addition, you can refer to 
    185 [CHANGELOG.md](https://github.com/census-instrumentation/opencensus-java/blob/master/CHANGELOG.md)
    186 for a list of major changes since last release.
    187 
    188 Please pick major or important user-visible changes only.
    189 
    190 ## Update release versions in documentations and build files
    191 
    192 After releasing is done, you need to update all readmes and examples to point to the
    193 latest version.
    194 
    195 1. Update README.md and gradle/maven build files on `master` branch:
    196 
    197 ```bash
    198 $ git checkout -b bump-document-version master
    199 $ BUILD_FILES=(
    200   examples/build.gradle
    201   examples/pom.xml
    202   )
    203 $ README_FILES=(
    204   README.md
    205   contrib/appengine_standard_util/README.md
    206   contrib/exemplar_util/README.md
    207   contrib/grpc_util/README.md
    208   contrib/http_util/README.md
    209   contrib/log_correlation/log4j2/README.md
    210   contrib/log_correlation/stackdriver/README.md
    211   contrib/monitored_resource_util/README.md
    212   contrib/spring/README.md
    213   contrib/spring_sleuth_v1x/README.md
    214   contrib/zpages/README.md
    215   exporters/stats/prometheus/README.md
    216   exporters/stats/signalfx/README.md
    217   exporters/stats/stackdriver/README.md
    218   exporters/trace/instana/README.md
    219   exporters/trace/logging/README.md
    220   exporters/trace/jaeger/README.md
    221   exporters/trace/ocagent/README.md
    222   exporters/trace/stackdriver/README.md
    223   exporters/trace/zipkin/README.md
    224   )
    225 # Substitute versions in build files
    226 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*LATEST_OPENCENSUS_RELEASE_VERSION\)/'$MAJOR.$MINOR.$PATCH'\1/' \
    227  "${BUILD_FILES[@]}"
    228 # Substitute versions in build.gradle examples in README.md
    229 $ sed -i 's/\(\(compile\|runtime\).\+io\.opencensus:.\+:\)[0-9]\+\.[0-9]\+\.[0-9]\+/\1'$MAJOR.$MINOR.$PATCH'/' \
    230  "${README_FILES[@]}"
    231 # Substitute versions in maven pom examples in README.md
    232 $ sed -i 's/\(<version>\)[0-9]\+\.[0-9]\+\.[0-9]\+/\1'$MAJOR.$MINOR.$PATCH'/' \
    233  "${README_FILES[@]}"
    234 ```
    235 
    236 2. Update bazel dependencies for subproject `examples`:
    237 
    238     - Follow the instructions on [this
    239     page](https://docs.bazel.build/versions/master/generate-workspace.html) to
    240     install bazel migration tool. You may also need to manually apply
    241     this [patch](
    242     https://github.com/nevillelyh/migration-tooling/commit/f10e14fd18ad3885c7ec8aa305e4eba266a07ebf)
    243     if you encounter `Unable to find a version for ... due to Invalid Range Result` error when
    244     using it.
    245 
    246     - Use the following command to generate new dependencies file:
    247 
    248     ```bash
    249     $ bazel run //generate_workspace -- \
    250     --artifact=com.google.guava:guava-jdk5:23.0
    251     --artifact=com.google.guava:guava:23.0 \
    252     --artifact=io.grpc:grpc-all:1.9.0 \
    253     --artifact=io.opencensus:opencensus-api:$MAJOR.$MINOR.$PATCH \
    254     --artifact=io.opencensus:opencensus-contrib-grpc-metrics:$MAJOR.$MINOR.$PATCH \
    255     --artifact=io.opencensus:opencensus-contrib-zpages:$MAJOR.$MINOR.$PATCH \
    256     --artifact=io.opencensus:opencensus-exporter-stats-prometheus:$MAJOR.$MINOR.$PATCH \
    257     --artifact=io.opencensus:opencensus-exporter-stats-stackdriver:$MAJOR.$MINOR.$PATCH \
    258     --artifact=io.opencensus:opencensus-exporter-trace-logging:$MAJOR.$MINOR.$PATCH \
    259     --artifact=io.opencensus:opencensus-exporter-trace-stackdriver:$MAJOR.$MINOR.$PATCH \
    260     --artifact=io.opencensus:opencensus-impl:$MAJOR.$MINOR.$PATCH \
    261     --artifact=io.prometheus:simpleclient_httpserver:0.3.0 \
    262     --repositories=http://repo.maven.apache.org/maven2
    263     Wrote
    264     /usr/local/.../generate_workspace.runfiles/__main__/generate_workspace.bzl
    265     ```
    266 
    267     - Copy this file to overwrite `examples/opencensus_workspace.bzl`.
    268 
    269     - Use the following command to rename the generated rules and commit the
    270       changes above:
    271 
    272     ```bash
    273     $ sed -i 's/def generated_/def opencensus_/' examples/opencensus_workspace.bzl
    274     $ git commit -a -m "Update release versions for all readme and build files."
    275     ```
    276 
    277 3. Go through PR review and merge it to GitHub master branch.
    278 
    279 4. In addition, create a PR to mark the new release in 
    280 [CHANGELOG.md](https://github.com/census-instrumentation/opencensus-java/blob/master/CHANGELOG.md)
    281 on master branch. Once that PR is merged, cherry-pick the commit and create another PR to the 
    282 release branch (branch v$MAJOR.$MINOR.x).
    283 
    284 
    285 ## Known Issues
    286 
    287 ### Deployment for tag v0.5.0
    288 To rebuild the releases on the tag v0.5.0 use:
    289 ```bash
    290 $ ./gradlew clean build && ./gradlew uploadArchives
    291 ```
    292 
    293 If option `-Dorg.gradle.parallel=false` is used, you will hit [this bug](https://issues.sonatype.org/browse/OSSRH-19485)
    294 caused by [this bug](https://github.com/gradle/gradle/issues/1827) in gradle 3.5.
    295