Merge pull request #1102 from watson-developer-cloud/release-docs

Update release documentation

Author: germanattanasio

.github/bintray-new-version.png

@@ -1,50 +1,45 @@
-# Release Process
+# Release process
 
-* code: https://github.com/watson-developer-cloud/java-sdk
-* maven: http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22java-sdk%22
+The Java SDK has been configured so that releases should happen **automatically**.
 
-## Guide to uploading artifacts to the Central Repository
+If everything goes smoothly, commits to `master` should trigger new package versions using [semantic-release](https://github.com/semantic-release/semantic-release), which bases the release type (major, minor, patch, none) on the commit messages, which should always follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/).
 
-We use Sonatype as repository manager, it's used as the input channel for the Central Repository running the Sonatype Open Source Repository Hosting(OSSRH) service.
+When new versions are released, the code is pushed to Bintray and synced to Maven Central. The packages can be found [here](https://bintray.com/ibm-cloud-sdks/ibm-cloud-sdk-repo) on Bintray and [here](https://search.maven.org/search?q=com.ibm.watson) on Maven Central.
 
-### Prerequisites
+The Javadocs for the new version should also be pushed automatically. Docs are located in the `gh-pages` branch of the repo, and that gets synced to the following GitHub Pages link: http://watson-developer-cloud.github.io/java-sdk/
 
-If you are not familiar with Sonatype and/or the maven release process please read the following material:
+If things **don't** go smoothly, you'll need to follow some other instructions to get things in order.
 
-* Sonatype: http://central.sonatype.org/pages/apache-maven.html
-* Releasing artifacts to Sonatype: http://kirang89.github.io/blog/2013/01/20/uploading-your-jar-to-maven-central/
-* Install GPG, and create a public key. More info: http://central.sonatype.org/pages/working-with-pgp-signatures.html
+## Fixing broken releases
 
-### Releasing
-As part of your PR into `master` for a release, make a commit updating version number strings across the SDK. To do this, we use [bumpversion](https://github.com/peritus/bumpversion).
+### Travis timeouts
 
-To use `bumpversion`, simply run the following command with the proper semantic version for your desired release:
-```bash
-bumpversion major|minor|patch
-```
+The most common reason for a release to fail is because of a Travis timeout. Builds are only allowed to run for a maximum of 1 hour, and unfortunately the syncing process between Bintray and Maven Central can be slow enough to go over this time limit sometimes. If this happens, you should do the following:
 
-After you've merged your PR and After the `master` branch successfully builds from the release changes, check out the `master` branch and perform a release deployment to OSSRH (Staging) with:
-```bash
-gradle release
-```
-You will have to answer prompts for versions and tags. That will tag and commit a new version into your repository automatically.
+- Navigate to the code on Bintray at [this URL](https://bintray.com/ibm-cloud-sdks/ibm-cloud-sdk-repo). If you're not a member of the ibm-cloud-sdks organization, ask the maintainer of this SDK repo for access.
+- Navigate to the "Maven Central" tab in each of the packages that didn't sync. Here's an example: https://bintray.com/ibm-cloud-sdks/ibm-cloud-sdk-repo/com.ibm.watson%3Alanguage-translator#central. You can figure out which packages to sync manually by checking the failed Travis build log or by looking at the "Last Synced" date for the package.
+- Click the "Sync" button. If you need to provide Sonatype credentials, you can also ask the maintainer of this SDK repo for those.
 
-After the above commits pass, `git checkout` the new tag branch for your release. In that branch, execute the following command:
+    <img alt="Bintray sync"  width="600" src="./.github/bintray-sync.png">
 
-```bash
-./gradlew uploadArchives -Psigning.keyId=<keyId> -Psigning.password=<keyPassword> -Psigning.secretKeyRingFile=<pathToKeyRingFile> -PossrhUsername=<sonatypeUsername> -PossrhPassword=<sonatypePassword>
-```
+- After doing this with all of the necessary packages, you can verify that things worked by checking the available versions on [Maven Central](https://search.maven.org/search?q=com.ibm.watson). This could take up to an hour.
 
-The arguments should be populated with the following:
-- `-Psigning.keyId`: The ID of your public key you created after following the link in the prerequisites
-- `-Psigning.password`: Your password you created for making public GPG keys
-- `-Psigning.secretKeyRingFile`: After creating your public key, you create your keyring file with the following command and use the absolute path to your new file:
+### Unsuccessful Bintray deployment
 
-```bash
-gpg --export-secret-keys -o <outputFilename>.gpg
-```
+This case is much more unlikely, since integration tests don't run on `master` and builds are very unlikely to be passing in a PR but fail once it's merged. Nevertheless, if this does happen and files aren't deployed to Bintray, you'll need to follow some steps to do this manually:
 
-- `-PossrhUsername`: Your Sonatype username
-- `-PossrhPassword`: Your Sonatype password
+- Navigate to the code on Bintray at [this URL](https://bintray.com/ibm-cloud-sdks/ibm-cloud-sdk-repo). If you're not a member of the ibm-cloud-sdks organization, ask the maintainer of this SDK repo for access.
+- For each package in the SDK, if the new version isn't present, you can add it by navigating to the package and adding it manually:
 
-Assuming this command works properly, you should be able to then log into Sonatype and close and release the repository.
+    <img alt="Bintray new version"  width="600" src="./.github/bintray-new-version.png">
+
+- To add the files, make sure to first generate all of the necessary artifacts locally. Check out the new release tag and generate them with the following commands (from the SDK repo):
+  ```
+  git checkout {release tag}
+  ./gradlew shadowJar
+  ```
+- In the new version of the package on Bintray, add the files with the "Upload Files" button. Follow the file structure of previous releases to ensure everything works properly. The files to add should be in the `build/libs` folder of each local package in the SDK.
+
+    <img alt="Bintray upload files"  width="600" src="./.github/bintray-upload-files.png">
+
+- Finally, be sure to sync the artifacts with Maven Central. You can look at the [Travis timeouts](#travis-timeouts) section above for more information on this.

.github/bintray-sync.png

@@ -61,7 +61,7 @@ public class VisualRecognitionIT extends WatsonServiceTest {
   private static final String VERSION = "2019-02-11";
   private static final String RESOURCE = "src/test/resources/visual_recognition/v4/";
 
-  private static final String COLLECTION_ID = "684777e5-1f2d-40e3-987f-72d36557ef46";
+  private static final String COLLECTION_ID = "10e96193-0e08-406b-b8fb-b5b9ea9fe99a";
   private static final String GIRAFFE_CLASSNAME = "giraffe";
   private static final String SINGLE_GIRAFFE_IMAGE_PATH = RESOURCE + "giraffe_to_classify.jpg";
   private static final String GIRAFFE_POSITIVE_EXAMPLES_PATH = RESOURCE + "giraffe_positive_examples.zip";