From 1800bf5a988e2a49bf61e44b4678eeaabf065b57 Mon Sep 17 00:00:00 2001
From: Jose Carlos Venegas Munoz <jose.carlos.venegas.munoz@intel.com>
Date: Tue, 2 Oct 2018 11:01:33 -0500
Subject: [PATCH] docs: Document release process - tools.

Document flow to create a release based in the tools
from this repository.

Fixes: #207

Signed-off-by: Jose Carlos Venegas Munoz <jose.carlos.venegas.munoz@intel.com>
---
 release/release.md | 120 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 release/release.md

diff --git a/release/release.md b/release/release.md
new file mode 100644
index 00000000..f54d45f3
--- /dev/null
+++ b/release/release.md
@@ -0,0 +1,120 @@
+# How to do a Kata Containers Release
+
+If you are reading this document, you might want to create a Kata Containers
+Release.
+
+The Kata Containers Release Process is defined in the following
+[document][release-process-definition]. To simplify this process, we have
+created a [Release Checklist][release-checklist].
+
+Finally, to simplify the Release Checklist process we have automated most of the
+process.
+
+
+
+## Requirements
+- It is "safe" to run this process on any machine. It creates all assets in
+  sub-directories and should not modify the entire system.
+
+- It is recommended to get at least 2 GB of free disk space to perform these tasks.
+
+- [Go](https://golang.org/doc/install#)
+
+- [hub](https://github.com/github/hub)
+  If you use GitHub 2FA, configure the hub manually to create a file ~/.config/hub
+  ```yaml
+  github.com:
+  - user: YOUR_USER
+  oauth_token: TOKEN
+  protocol: https
+  ```
+- OBS account with permissions on /home:katacontainers (https://build.opensuse.org/project/subprojects/home:katacontainers)
+
+- GitHub permissions to push tags and creates Releases in Kata repositories.
+
+- GPG configured to sign git tags. https://help.github.com/articles/generating-a-new-gpg-key/
+
+- You should configure your GitHub to use your ssh keys (to push to branches). See https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/.
+    * As an alternative, configure hub to push and fork with https, `git config --global hub.protocol https` (Not tested yet) *
+
+
+## Get the packaging Kata repository.
+The steps described here are safe to repeat more than one time, it is safe to
+repeat in case of unexpected issue. And is it not required start from the
+begging.
+
+would be worth stating somewhere whether particular steps can be repeated safely or not
+```bash
+$ go get -d github.com/kata-containers/packaging
+```
+
+## Release process
+
+```bash
+$ cd ${GOPATH}/src/github.com/kata-containers/packaging
+# make sure you are up-to-date.
+$ git pull
+```
+1. Bump repositories
+```bash
+$ cd ${GOPATH}/src/github.com/kata-containers/packaging/release
+$ export NEW_VERSION=X.Y.Z
+$ export BRANCH="master"
+$ ./update-repository-version.sh -p ksm-throttler "$NEW_VERSION" "$BRANCH"
+$ ./update-repository-version.sh -p proxy "$NEW_VERSION" "$BRANCH"
+$ ./update-repository-version.sh -p shim "$NEW_VERSION" "$BRANCH"
+$ ./update-repository-version.sh -p runtime "$NEW_VERSION" "$BRANCH"
+$ ./update-repository-version.sh -p osbuilder "$NEW_VERSION" "$BRANCH"
+$ ./update-repository-version.sh -p agent "$NEW_VERSION" "$BRANCH"
+```
+
+The commands from above will create a github pull request in the Kata projects.
+Work with the Kata approvers to verify that the CI works and the PR are merged.
+
+2. Create GitHub tags:
+
+After all the PRs from the previous step are complete, create GitHub tags.
+
+```bash
+$ cd ${GOPATH}/src/github.com/kata-containers/packaging/release
+$  ./tag_repos.sh -p -b "$BRANCH" tag
+```
+
+This creates tags for all the Kata repos.
+
+3. Create the Kata Containers image and upload it to GitHub:
+```bash
+$ cd ${GOPATH}/src/github.com/kata-containers/packaging/release
+$ ./publish-kata-image.sh -p ${NEW_VERSION}
+```
+
+4. Create the Kata static binaries tarball and upload it to GitHub::
+```bash
+$ cd ${GOPATH}/src/github.com/kata-containers/packaging/release
+$ ./kata-deploy-binaries.sh -p ${NEW_VERSION}
+```
+
+5. Create Kata packages:
+
+```bash
+$ cd ${GOPATH}/src/github.com/kata-containers/packaging/obs-packaging
+# Optional, if release is a new stable branch ./create-pkg-branch.sh ${BRANCH}
+$./gen_versions_txt.sh ${BRANCH}
+$PUSH=1 OBS_SUBPROJECT="releases:$(uname -m):${BRANCH}" ./build_from_docker.sh ${NEW_VERSION}
+```
+
+6. Create release notes:
+```bash
+$ cd ${GOPATH}/src/github.com/kata-containers/packaging/release
+# Note: LAST_VERSION is where the script should start to get changes.
+$ ./runtime-release-notes.sh LAST_VERSION ${NEW_VERSION} > notes.md
+# Add the release notes in GitHub runtime.
+$ hub -C "${GOPATH}/src/github.com/kata-containers/runtime" release edit -F notes.md
+```
+
+7. Announce release:
+
+Publish in Slack and Kata mailing list kata-dev@lists.katacontainers.io that new release is ready.
+
+[release-process-definition]: https://github.com/kata-containers/documentation/blob/master/Releases.md
+[release-checklist]: https://github.com/kata-containers/documentation/blob/master/Release-Checklist.md