Create README for release process

[ajkannan]

[jgeewax]

I think the closest we have on this is in CONTRIBUTING.rst on gcloud-python? https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/CONTRIBUTING.rst

maybe we call this RELEASING.md ?

[ajkannan]

I'm going to document the release process in this issue for now. We can comment on it, update it, and let the documentation live elsewhere once we've made the necessary changes.

[ajkannan]

Overview

Most of the release process is handled by the after_success.sh script, triggered after Travis CI successfully completes a non-PR build. A new artifact will be released to Maven Central Repository via Travis CI when "-SNAPSHOT" is not included in the version (as listed in the base directory's pom.xml). The website and README files will also be updated automatically in this case. When "-SNAPSHOT" is included in the version, Travis only updates the artifact in the snapshot repository.

To push a release version

1. Run utilities/update_pom_version.sh from the repository's base directory.
   This script takes an optional argument denoting the new version. By default, if the current version is X.Y.Z-SNAPSHOT, the script will update the version in all the pom.xml files to X.Y.Z. If desired, another version can be supplied via command line argument instead.
2. Create a PR to update the pom.xml version.
   After this PR is merged into GoogleCloudPlatform/gcloud-java, Travis CI will push a new website to GoogleCloudPlatform/gh-pages and push a new artifact to the Maven Central Repository.
3. Run utilities/update_pom_version.sh again (to include "-SNAPSHOT" in the project version).
   As mentioned before, there is an optional version argument. By default, the script will update the version from "X.Y.Z" to "X.Y.Z+1-SNAPSHOT". Suppose a different version is desired, for example X+1.0.0-SNAPSHOT. Then the appropriate command to run would be utilities/update_pom_version.sh X+1.0.0-SNAPSHOT.
4. Create and merge in another PR to reflect the updated project version.

To push a snapshot version

Pushing a snapshot is completely automated. If "-SNAPSHOT" is included in the version denoted by the base directory's pom.xml, then an updated artifact will be pushed to the snapshot repository when Travis CI successfully completes a non-PR build.

Improvements

Tagging is not currently implemented, though it was discussed in #119. If the version updates continue to be manual, a one-line git tag command can be added to after_success.sh to correctly tag releases. However, if the release process becomes fully automated, tagging becomes a harder problem, as mentioned in that issue.

[aozarov]

Looks good and I am fine with having it in RELEASING.md.

As for the Improvements section. In the manual process how can we add the tag to after_sucess.sh
if that one is invoked by Travis?

Is the tag needed to be included in the local git before pushed or should we add another manual step after (2) to create a gitHub release?

[ajkannan]

I was thinking that we could add a lightweight tag (git tag v${SITE_VERSION}), then push it to the remote. However, it'd probably be nice to have some sort of annotation denoting what the release contains, and that's hard to automate. Also, since tags have to be unique, if something goes wrong with the release (say the build that triggers a github push passes, but the builds for java 8 fails because of javadoc errors), then we'd be in the business of deleting remote tags to fix the release, which is something we want to avoid.

[mziccard]

@ajkannan I think for the moment we can tag the commit at the end of after_success.sh (after publishing the artifact, once we know that everything worked as expected). We can then manually add annotations to the tag (changelog, acknowledgements, etc...)

[ajkannan]

After thinking about it a bit more, I think adding the lightweight tag, even at the end of after_success.sh, adds only a little while introducing extra risk. It's very possible to accidentally merge in other commits between the two pom.xml version change PRs, and if one build (say the java8 build) were to fail for platform-specific reasons and we accidentally merge the commit in anyways, then we'd have to spend time and effort to delete/move tags around.

If we're going to anyways manually add annotations to the tag, there's a option to "create tag on publish," when drafting the release, so I now support creating tags manually (for now at least).

[mziccard]

@ajkannan Sounds good to me. Even though we could assume we are careful enough not to merge other commits in between:)