Update release procedures (vmware#1637)

installer/docs/BUILD.md

@@ -155,13 +155,13 @@ Please note that you cannot trigger new CI builds manually, but have to promote
 
 Make sure `DRONE_SERVER` and `DRONE_TOKEN` environment variables are set before executing these commands.
 
-To promote existing successful CI build to staging...
+To promote existing successful CI build to staging (`vic-product-ova-builds` bucket):
 
 ``
 $ drone deploy --param VICENGINE=<vic_engine_version> --param VIC_MACHINE_SERVER=<vic_machine_server> --param ADMIRAL=<admiral_tag> --param HARBOR=<harbor_version> vmware/vic-product <ci_build_number_to_promote> staging
 ``
 
-To promote existing successful CI build to release...
+To promote existing successful CI build to release (`vic-product-ova-releases` bucket):
 
 ``
 $ drone deploy --param VICENGINE=<vic_engine_version> --param VIC_MACHINE_SERVER=<vic_machine_server> --param ADMIRAL=<admiral_tag> --param HARBOR=<harbor_version> vmware/vic-product <ci_build_number_to_promote> release

installer/docs/RELEASE.md

@@ -3,12 +3,14 @@
 All examples in this document assume the user's fork is at `origin` and `vmware/vic-product` is at
 `upstream`.
 
+
 ## Branching
 
 When the team is ready to build a release candidate, create a branch off of master based on the
-release version number. A tag for ongoing development should also be created at the commit after
-where the release branch begins. If there have been commits to master since the intended branch
-point, first create a tag for the release candidate, then create the branch from that tag.
+release version number. 
+
+A tag for ongoing development should also be created at the commit **after**
+the start of the release branch. The tagging procedure is documented in [Tagging](#Tagging). 
 
 ```
 git remote update
@@ -22,8 +24,11 @@ git push upstream
 Configure branch protection on Github to have the same protection as the master branch.
 `Protect this branch` and `Require pull request reviews before merging` should be set.
 
-Development should continue on master. Commits that need to be pulled into the release should be
-cherry picked into the release branch after they are merged into master.
+
+## Cherry picking
+
+Commits that need to be pulled into the release should be cherry picked into the release branch
+after they are merged into master.
 
 ```
 git remote update
@@ -38,54 +43,73 @@ git push upstream
 ## Tagging
 
 On the master branch, tag the commit for the first release candidate. On the
-following commit, tag `dev` for ongoing development.  For example, if the
+following commit, tag `dev` for ongoing development. For example, if the
 current release is `v1.2.0`, the first release candidate will be `v1.2.0-rc1` and
 the tag for ongoing development will be `v1.3.0-dev`.
 
-When the team is ready to release, tag the commit in the release branch (`v1.2.0`) and push the tag
-to Github.
-
 ```
 git remote update
 git checkout upstream/releases/1.2.0
 git tag -a v1.2.0-rc1 aaaaaaa
 git push upstream v1.2.0-rc1
 ```
 
-Tag `dev` on the release branch after a release. For example, if `v1.2.0` was tagged on
-`/releases/1.2.0` and there is work for `v1.2.1`, on the following commit, tag `v1.2.1-dev`.
+If there is not yet a commit after the start of the release branch, create an empty commit after
+the commit for the release branch. This empty commit will be tagged for ongoing development on master.
+
+```
+# Create empty commit on master
+git remote update
+git checkout upstream/master
+git commit --allow-empty -m "v1.3.0-dev"
+git push upstream
+
+# Tag empty commit for ongoing development
+git remote update
+git checkout upstream/master
+git tag -a v1.3.0-dev bbbbbbb
+git pubsh upstream v1.3.0-dev
+```
+
+After the release candidate has passed QA and the team is ready to release, tag the commit in the
+release branch (`v1.2.0`) and push the tag to Github.
 
 ```
 git remote update
 git checkout upstream/releases/1.2.0
-git tag -a v1.2.1-dev bbbbbbb
-git push upstream v1.2.1-dev
+git tag -a v1.2.0 ccccccc
+git push upstream v1.2.0
 ```
 
+### Point releases
 
-## Building Release
+After a release, tag `dev` on the release branch for ongoing development.
+For example, if `v1.2.0` was tagged on `/releases/1.2.0` and there is work for `v1.2.1`, on the
+following commit, tag `v1.2.1-dev`.
 
 ```
-git fetch --all --tags --prune
-git checkout tags/v1.2.0
+git remote update
+git checkout upstream/releases/1.2.0
+git tag -a v1.2.1-dev ddddddd
+git push upstream v1.2.1-dev
 ```
 
-Follow instructions in [How to build VIC Product OVA](BUILD.md)
 
 ## Github Releases
 
 After pushing the tag to Github, go to https://github.com/vmware/vic-product/releases/new
 
 Select the appropriate tag
 
-Title for follows form `VIC Product <tag>` (`VIC Product v1.2.0-rc1`)
+Release title follows form `vSphere Integrated Containers Appliance <tag>` (e.g. `vSphere Integrated Containers Appliance v1.2.0-rc1`)
 
 Description template for release candidates:
 ```
 OVA will contain:
-Admiral `v1.2.0-rc3`
-Harbor `harbor-offline-installer-v1.2.0-rc4.tgz`
-VIC Engine `vic_1.2.0-rc4.tar.gz`
+Admiral v1.2.0-rc3
+Harbor harbor-offline-installer-v1.2.0-rc4.tgz
+VIC Engine vic_1.2.0-rc4.tar.gz
+VIC Machine Server digest aaaaaaa
 ```
 
 If the release is a release candidate, mark `This is a pre-release`
@@ -94,12 +118,24 @@ If the release is a release candidate, mark `This is a pre-release`
 
 Description template for release version of the OVA:
 ```
-Admiral `v1.2.0`
-Harbor `harbor-offline-installer-v1.2.0.tgz`
-VIC Engine `vic_1.2.0.tar.gz`
+Admiral v1.2.0
+Harbor harbor-offline-installer-v1.2.0.tgz
+VIC Engine vic_1.2.0.tar.gz
+VIC Machine Server digest aaaaaaa
 
 ef6b71d98bb6650240008b5281e97bf8592d5fd726833883718f471ed665fc5b  vic-v1.2.0-aaaaaaaa.ova
 85eabdf7e58fed8c09e4f3c45b2caa974ae89a16  vic-v1.2.0-aaaaaaaa.ova
 ebc669f7b4cebf7501cf141e3b6fa2e3  vic-v1.2.0-aaaaaaaa.ova
 4741.43 MB
 ```
+
+
+## Building Release
+
+```
+git fetch --all --tags --prune
+git checkout tags/v1.2.0
+```
+
+Follow instructions in [How to build VIC Product OVA](BUILD.md)
+