Document how docs are handled before and during release. (#1388)

* Document how docs are handled before and during release.

Also split the super-long lines into paragraphs for ease of diff viewing
and reading, add some markup here and there, fix some typos and reword a
couple of unclear sentences.


Co-authored-by: Aleksey Dukhovniy <adukhovniy@mesosphere.io>
Co-authored-by: Ken Sipe <kensipe@gmail.com>

Signed-off-by: Marcin Owsiany <mowsiany@D2iQ.com>

RELEASE.md

@@ -4,11 +4,40 @@
 
 ### Master
 
-The HEAD of master is consider the most active development, to which, new features and bug fixes are applied. The expectation is that master will always build and pass tests. Development is incremental. It is expected that pull-requests are either complete, are not fully integrated into code execution path or have a feature switch which must be enabled until code completion is reached. HEAD on master is expected to be in a state that it could be released. The next major release will be tagged and released from master. If the current released version is `v0.3.1` and the next major release is `v0.4.0` when it is deemed appropriate `v0.4.0` will be tagged off master, followed by a release. From that tag work will continue on master. IF it is necessary in the future to have a patch release for `v0.4.1`, a branch will be created off the `v0.4.0` tag with the nomenclature of `releases\{major.minor}`, in this example `releases\0.4`. Branches with `releases/*` are protected branches in the repository.
+The `HEAD` of `master` branch is considered the most active development, to which new features and bug fixes are applied. The expectation is that master will always build and pass tests.
+Development is incremental. It is expected that pull-requests are either:
+ - complete and fully integrated into code execution path, or
+ - have a feature switch which must be enabled until code completion is reached.
+
+`HEAD` on master is expected to be in a state that it could be released.
+The next major release will be tagged and released from master.
+If the current released version is `v0.3.1` and the next major release is `v0.4.0`, then when it is deemed appropriate `v0.4.0` will be tagged off master, followed by a release.
+From that tag work will continue on master.
+
+*If* it is necessary in the future to have a patch release for `v0.4.1`, a branch will be created off the `v0.4.0` tag with the nomenclature of `releases/{major.minor}`, in this example `releases/0.4`.
+Branches matching `releases/*` are protected branches in the repository.
+
+The `HEAD` of the release branches follows the same conventions as master.  It is expected that `HEAD` of the release branch is always in a releasable state. The purpose of the release branch is for bug fixes only.  New features should not be targeted to a release branch.
+
+### Documentation
+
+Pull request for documentation (in the `kudo.dev` repo) should be prepared and reviewed at
+the same time as the pull request for any user-visible (documentation-worthy) change.
+The description for the code change PR should link to the documentation PR (and vice-versa).
+
+The documentation PR should be made against the `next-release` branch, and merged as soon as its
+corresponding PR(s) against the `kudo` repo is/are merged.
 
 ### Bug Fixes
 
-Bug fixes are expected to be worked on and applied to `master`.  If the fix is needed for a previous supported release version of KUDO, then a back port is expected. The bug pull request is expected to be marked with a `back port` label. It is easiest for the developer working on the bug to back port to a previous version. It is expected when possible that the back port is a `git cherry-pick` to a previous version, updating as necessary to conform to previous code and architecture. On occasion a cherry-pick is too much of a burden. In this case, fix the bug as a new pull request against the release branch. Provide the same title and details of the original pull request for traceability.
+Bug fixes are expected to be worked on and applied to `master`.
+
+If the fix is needed for a previously supported release version of KUDO, then a backport is expected.
+The bug fix pull request is expected to be marked with a `backport` label.
+If a bug fix has to be backported to a previous version, it is expected when possible that the backport is a `git cherry-pick`, updated if necessary to conform to previous code and architecture.
+
+On occasion a cherry-pick is too much of a burden. In this case, fix the bug as a new pull request against the release branch.
+Provide the same title and details of the original pull request for traceability.
 
 ## Release Request Process
 
@@ -23,19 +52,34 @@ The KUDO Project is aiming to do monthly minor releases but the period could be
 
 The official binaries for KUDO are created using [goreleaser](https://goreleaser.com/). The [.goreleaser.yml](.goreleaser.yml) defines the binaries which are supported for each release. Goreleaser is right now run manually from the RM computer. The current process to initiate a release is:
 
-1. Ensure you have credential `GITHUB_TOKEN` set. The env must include `export GITHUB_TOKEN=<personal access token>`. [Help](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) provided from Github. The token must grant full access to: repo, write:packages, read:packages.
+1. Ensure you have credential `GITHUB_TOKEN` set.
+The env must include `export GITHUB_TOKEN=<personal access token>`.
+[Help](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) provided from Github.
+The token must grant full access to: `repo`, `write:packages`, `read:packages`.
 1. Ensure you are logged into Docker hub and have rights to push to kudobuilder.
-1. Tag repo with expected release `git tag -a v0.2.0 -m "v0.2.0"`  && push tag `git push --tags`.
+1. Tag the `kudo` repo with expected release `git tag -a v0.2.0 -m "v0.2.0"` and push the tag `git push --tags`.
 1. Invoke goreleaser `goreleaser --rm-dist`.
 1. Update the GH release with Release highlights and a changelog. There is a draft that contains categorized changes since the last release, use this as a template. It provides categories for highlights and breaking changes, the issues there should get a more detailed description. After the contents are copied, the draft can be deleted.
-1. Send an announcement email to `kudobuilder@googlegroups.com` with the subject `[ANNOUNCE] Kudo $VERSION is released`
+1. Merge the `next-release` branch of the `kudo.dev` repo into its `master` with:
+   ```bash
+   cd kudo.dev
+   git checkout master && git pull && git merge origin/next-release
+   git push origin master
+   ```
+   Immediately after that, re-create the `next-release` from the tip of `master` with:
+   ```bash
+   git branch -D next-release
+   git checkout -b next-release
+   git push origin +HEAD
+   ```
+1. Send an announcement email to [kudobuilder@googlegroups.com](https://groups.google.com/forum/#!forum/kudobuilder) with the subject `[ANNOUNCE] Kudo $VERSION is released`
 1. Create a PR against [kudobuilder/kudo.dev](https://github.com/kudobuilder/kudo.dev) with an according [blog post](https://kudo.dev/internal-docs/blog-index.html#release-posts).
 1. Run `./hack/generate_krew.sh` and submit the generated `kudo.yaml` to https://github.com/kubernetes-sigs/krew-index/.
 1. Update KUDO_VERSION [in the Makefile](https://github.com/kudobuilder/operators/blob/master/Makefile#L2) of operators repo
 
 **Note:** If there are issues with the release, any changes to the repository will result in it being considered "dirty" and not in a state to be released.
 It is possible outside of the standard release process to build a "snapshot" release using the following command: `goreleaser release --skip-publish --snapshot --rm-dist`
-This process will create a "dist" folder with all the build artifacts. The changelog is not created unless a full release is executed. If you are looking to get a "similar" changelog, install [github-release-notes](https://github.com/buchanae/github-release-notes) and execute `github-release-notes -org kudobuilder -repo kudo -since-latest-release`.
+This process will create a `dist` folder with all the build artifacts. The changelog is not created unless a full release is executed. If you are looking to get a "similar" changelog, install [github-release-notes](https://github.com/buchanae/github-release-notes) and execute `github-release-notes -org kudobuilder -repo kudo -since-latest-release`.
 
 ### Cutting a Release Branch