Add review notes to the readme

We need to document general guidelines for reviewing release requests.

This is following the recent gate breakage with oslo.utils 1.4.1.

The intent here is mostly for the special cases which impact stable branches,
but the semver reminder is important for non-stable branches also since
improper versioning on master where semver wasn't followed, e.g. incrementing
a patch version when the minor version should have been updated, has led to
a lot of the problems we see with stable branches.

Related-Bug: #1496650

Change-Id: I4c7013e265bb533dbac2c8804dea01dacff5de4b

README.rst

@@ -26,6 +26,64 @@ the stable release is requested by the stable maintenance team, it
 should be acknowledged by the PTL or release liaison to ensure that
 the development team is aware of the coming change.
 
+Reviewing a Release Request
+---------------------------
+
+Care needs to be taken when reviewing a release request such that the version
+proposed (1) follows semver rules and (2) will not cause issues between
+branches, particularly stable branches (at least stable branches that are not
+yet using upper-constraints checking in CI runs, which is anything before
+stable/liberty).
+
+General notes when reviewing a release request:
+
+* Make sure you follow semantic versioning rules `semver <http://semver.org/>`_
+  when picking the version number. In particular, if there is a change going
+  into this release which requires a higher minimum version of a dependency,
+  then the **minor** version should be incremented.
+
+  .. note:: The exception to this rule is when the versions of a project are
+    pinned between minor versions in stable branches. In those cases we
+    frequently release global-requirements syncs with a patch version to fix
+    the target branch, e.g. stable/juno, but don't increment the minor version
+    to avoid it being used in a different branch, like stable/kilo.
+    Someone from the
+    `stable-maint-core <https://review.openstack.org/#/admin/groups/530,members>`_
+    team should +1 a change like this before it's approved.
+
+The following rules apply mostly to stable branches and therefore a member of
+the `stable-maint-core <https://review.openstack.org/#/admin/groups/530,members>`_
+team should +1 the following types of changes before they are approved.
+
+* For libraries, check global-requirements.txt (g-r) in the
+  `openstack/requirements repo <http://git.openstack.org/cgit/openstack/requirements/>`_
+  to make sure the version you are about to release does not cause a
+  conflict and wedge the gate. Typically this is only a concern on stable
+  branches with (un)capped dependencies.
+
+  Typical examples of this kind of break (before upper-constraints are used):
+
+  #. A stable branch, for example stable/juno, has uncapped dependencies on a
+     library and a version is released on a newer branch, e.g. stable/kilo,
+     and that version has updated requirements from global-requirements in
+     stable/kilo which conflict with the versions of libraries allowed in
+     stable/juno. This then leads to ContextualVersionConflict failures when
+     installing packages on stable/juno.
+  #. Similar to the point above, but if there are overlapping version ranges
+     between two branches, like stable/juno and stable/kilo, you can have the
+     same kinds of issues where a release from one branch which has g-r syncs
+     specific to that branch gets used in the other branch and things break.
+     We saw this happen with oslo.utils 1.4.1 which was intended for
+     stable/juno consumption but because stable/kilo g-r allowed that version,
+     we broke stable/kilo CI jobs since 1.4.1 had juno-level dependencies.
+
+* The rule of thumb is that branches should not overlap versions at the minor
+  version range. For example, stable/juno can require foo>=1.1,<1.2 and
+  stable/kilo can require foo>=1.2,<1.3. In this way only patch-level versions
+  are released for foo on stable/juno and stable/kilo. The pin at the minor
+  version range prevents those patch-level versions from breaking each other's
+  branch.
+
 Release Approval
 ================