Merge branch 'nolith-process-doc' into 'master'

Update process with release-tools

Closes #2471

See merge request gitlab-org/gitaly!1871

2 files changed, 132 insertions, 64 deletions

diff --git a/.gitlab/issue_templates/Security Release.md b/.gitlab/issue_templates/Security Release.md
index 74bd350c4..c367dcc89 100644
--- a/.gitlab/issue_templates/Security Release.md
+++ b/.gitlab/issue_templates/Security Release.md
@@ -15,12 +15,12 @@ GitLab at the correct times.
 
 ## Version Matrix
 
-| GitLab-CE Branch | Gitaly Tag/Branch | Gitaly MR          |
-|------------------|-------------------|--------------------|
-| `master`         | **TBD**           | <MR link>          |
-| `12.X`           | `1-X-stable`      | <backport MR link> |
-| `12.X`           | `1-X-stable`      | <backport MR link> |
-| `12.X`           | `1-X-stable`      | <backport MR link> |
+| GitLab Branch | Gitaly Branch  | Gitaly MR          |
+|---------------|----------------|--------------------|
+| `master`      | **TBD**        | <MR link>          |
+| `12.X`        | `12-X-stable`  | <backport MR link> |
+| `12.Y`        | `12-Y-stable`  | <backport MR link> |
+| `12.Z`        | `12-Z-stable`  | <backport MR link> |
 
 ## Process
 
@@ -42,45 +42,17 @@ As a sanity check, you can verify your repository only points to remotes in
    - [ ] Once finished and approved, **DO NOT MERGE**. Merging into master
      will happen later after the security release is public.
 - **Contributor:** Backport fixes
-   - [ ] Note what version of Gitaly you're backporting by opening
-     [`GITALY_SERVER_VERSION`][gitaly-ce-version] for each supported GitLab-CE fill out
-     the [version matrix](#version-matrix) above.
-- **Contributor**: Determine if Gitaly stable branches exist for all needed
-  fixes.
-   - [ ] If all of them exist, also mark the next section as complete and skip.
-     Otherwise, reassign the maintainer to complete the next section.
-- **Maintainer:** If a Gitaly stable branch `X-Y-stable` in the [table above](#version-matrix)
-  does not exist yet, perform the following steps in a repository cloned
-  from `gitlab.com` (since we will rely on the public Gitaly repo to push
-  these stable branches to `dev.gitlab.org`):
-    - [ ] For each missing stable branch:
-       1. `git branch X-Y-stable vX.Y.0`
-       1. `git push --set-upstream origin X-Y-stable`
-    - Reassign to the contributor.
+   - [ ] Fill out the [version matrix](#version-matrix) above
+     checking if all the versions are affected and require a fix
 - **Contributor:**
    - [ ] Backport fixes:
       1. Manually squash all commits in your MR to Gitaly master and force push it to your feature branch on `dev.gitlab.org`.
       1. Cherry pick that squashed commit into a backport MR for all Gitaly target stable branches on `dev.gitlab.org`.
       1. Link all backport MR's into the [above table](#version-matrix).
       1. Reassign to Maintainer
-- **Maintainer:** After each stable branch merge request is approved and
-  merged, run the release script to release the new version:
-    - [ ] For each backported MR:
-       1. Ensure that `gitlab.com` is not listed in any of the remotes: `git remote -v`
-       1. `git checkout X-Y-stable`
-       1. `git pull`
-       1. `_support/release X.Y.Z` (where `Z` is the new incremented patch version)
-       1. Upon successful vetting of the release, run `git push origin $TAGNAME`
-          for each tag.
-    - Reassign to contributor
-- **Contributor:** Bump Gitaly in GitLab projects:
-   - [ ] For each version of GitLab in the [table above](#version-matrix),
-     create an MR on both
-     [GitLab-CE](https://dev.gitlab.org/gitlab/gitlabhq) and
-     [GitLab-EE](https://dev.gitlab.org/gitlab/gitlab-ee) on `dev.gitlab.org`
-     to bump the version in the `GITALY_SERVER_VERSION` file. Make sure you
-     follow the [usual security process][gitlab-sec-process].
-   - Reassign to maintainer
+- **Maintainer:**
+    - [ ] Review and merge each stable branch merge request
+    - tagging and version bump will be automated by `release-tools`
 
 ### Only after the security release occurs and the details are made public
 
diff --git a/doc/PROCESS.md b/doc/PROCESS.md
index 46616e76b..e732da767 100644
--- a/doc/PROCESS.md
+++ b/doc/PROCESS.md
@@ -19,31 +19,127 @@ For customers, who don't use chatops, an [HTTP API is available][ff-api].
 
 ### Gitaly Releases
 
-Gitaly uses [SemVer](https://semver.org) version numbering.
-
-#### Branching Model
-
-All `vX.Y.0` tags get created on the `master` branch. We only make patch
-releases when targeting a GitLab stable branch. Patch releases
-(`vX.Y.1`, `vX.Y.2`, ...) must be made on stable branches (`X-Y-stable`)
-in the Gitaly repository.
-
-There should be **no patch releases on `master`**. Gitaly patch releases should
-only be used for GitLab stable branches. If the release is not for a
-GitLab stable branch, just increment the minor (or major) version
-counter.
-
-#### Creating a release
-
-- Pick a release number (x.y.z)
-- Check out the master branch on your local machine
-- run `_support/release x.y.z`
-
-Where x.y.z is a semver-compliant version number.
-
-- The release will not yet be published, to prevent accidental leakage of security bug fixes. Run `_support/publish vX.Y.Z` to publish.
-- The pipeline of a tag will create a merge request on the GitLab codebase to bump the Gitaly server version, and this will be assigned to you. Once the build has
-  completed successfully, assign it to a maintainer for review.
+Gitaly releases are tagged automatically by [`release-tools`](https://gitlab.com/gitlab-org/release-tools) when a Release Manager tags a GitLab version.
+
+#### Major or minor releases
+
+Once we release GitLab X.Y.0, we also release gitaly X.Y.0 based on the content of `GITALY_SERVER_VERSION`.
+This version file is automatically updated by `release-tools` during auto-deploy picking.
+
+Because gitaly master is moving we need to take extra care of what we tag.
+
+Let's imagine a situation like this on `master`
+
+```mermaid
+graph LR;
+  A-->b0;
+  A-->B;
+  b0:::branch-->b1;
+  b1:::branch-->B;
+  B-->C;
+  B-->c0;
+  c0:::branch-->C;
+  classDef branch fill:#f96;
+  classDef tag fill:yellow;
+```
+
+Commit `C` is picked into auto-deploy and the build is successfully deployed to production
+
+We are ready to tag `v12.9.0` but there is a new merge commit, `D`, on gitaly `master`.
+
+```mermaid
+graph LR;
+  A-->b0;
+  A-->B;
+  b0:::branch-->b1;
+  b1:::branch-->B;
+  B-->C;
+  B-->c0;
+  c0:::branch-->C;
+  C-->D;
+  C-->d0;
+  d0:::branch-->D
+  classDef branch fill:#f96;
+  classDef tag fill:yellow;
+```
+
+We cannot tag on `D` as it never reached production.
+
+`release-tools` follows this algoritm:
+1. create a stable branch from `GITALY_SERVER_VERSION` (commit `C`),
+1. bump the version and
+1. prepare the changelog (commit `C'`).
+
+Then we tag this commit and we merge back to `master`
+
+```mermaid
+graph LR;
+  A-->b0;
+  A-->B;
+  b0:::branch-->b1;
+  b1:::branch-->B;
+  B-->C;
+  B-->c0;
+  c0:::branch-->C;
+  C-->D;
+  C-->d0;
+  d0:::branch-->D
+  C-->C';
+  id1>v12.9.0]:::tag-->C';
+  D-->E;
+  C':::stable-->E;
+  classDef branch fill:#f96;
+  classDef tag fill:yellow;
+  classDef stable fill:green;
+```
+
+Legend
+```mermaid
+graph TD;
+  A["master commit"];
+  b0["feature branch commit"]:::branch;
+  id1>tag]:::tag;
+  C["stable branch commit"]:::stable;
+  classDef branch fill:#f96;
+  classDef tag fill:yellow;
+  classDef stable fill:green;
+```
+
+With this solution, the team can autonomously tag any RC they like, but the other releases are handled by the GitLab tagging process.
+
+#### Patch releases
+
+The Gitaly team usually works on patch releases in the context of a security release.
+
+The release automation creates the stable branches, tagging the stable branch is automated in `release-tools` as well.
+A Gitaly maintainer will only take care of merging the fixes on the stable branch.
+
+For patch releases, we don't merge back to master. But `release-tools` will commit a changelog update to both the patch release, and the master branch.
+
+#### Creating a release candidate
+
+Release candidate (RC) can be created with a chatops command.
+This is the only type of release that a developer can build autonomously.
+
+When working on a GitLab feature that requires a minimum gitaly version,
+tagging a RC is a good way to make sure the gitlab feature branch has the proper gitaly version.
+
+- Pick the current milestone (i.e. 12.9)
+- Pick a release candidate number, you can check `VERSION` to see if we have one already (12.9.0-rc1)
+- run `/chatops run gitaly tag 12.9.0-rc1`
+- The release will be published
+- The [pipeline of a tag](https://gitlab.com/gitlab-org/gitaly/pipelines?scope=tags&page=1)
+  has a **manual** job, `update-downstream-server-version`, that will create a merge request on the GitLab codebase to bump the Gitaly server version, and this will be assigned to you. 
+  Once the build has completed successfully, assign it to a maintainer for review.
+
+### Publishing the ruby gem
+
+If an updated version of the ruby proto gem is needed, it can be published to rubygems.org with the `_support/publish-gem` script.
+
+If the changes needed are not yet released, [create a release candidate](#creating-a-release-candidate) first.
+
+- Checkout the tag to publish (vX.Y.Z)
+- run `_support/publish-gem X.Y.Z`
 
 ##### Security release