Release Automation

Tracking releases through yaml file similar to the openstack/releases
project.

Includes a schema file to be for validation, jobs for creating gerrit
branches and stable branch jobs, and documentation for projects on
creating their releases.

Change-Id: Id1876482723e01806c0a6932126dff5ea314eae5
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

2 files changed, 164 insertions, 0 deletions

diff --git a/docs/release/index.rst b/docs/release/index.rst
index d7d8acd39..49cd00bdb 100644
--- a/docs/release/index.rst
+++ b/docs/release/index.rst
@@ -13,5 +13,6 @@ Releasing OPNFV
    :maxdepth: 2
 
    release-process
+   release-automation
    stable-branch-guide
    versioning
diff --git a/docs/release/release-automation.rst b/docs/release/release-automation.rst
new file mode 100644
index 000000000..213e5ad3b
--- /dev/null
+++ b/docs/release/release-automation.rst
@@ -0,0 +1,163 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _release-automation:
+
+==================
+Release Automation
+==================
+
+This page describes how projects can take advantage of the release
+automation introduced in Fraser for creating their stable branch, and
+stable branch Jenkins jobs.
+
+It also describes the structures of the ``releases`` directory and the
+associated scripts.
+
+Stable Branch Creation
+----------------------
+
+If your project participated in the last release (beginning with
+Euphrates), perform the following steps:
+
+#. Copy your project's release file to the new release directory. For
+   example::
+
+     cp releases/euphrates/apex.yaml releases/fraser/apex.yaml
+
+#. For projects who are participating the in the stable release process for
+   the first time, you can either copy a different project's file and
+   changing the values to match your project, or use the following
+   template, replacing values marked with ``<`` and ``>``:
+
+   .. code-block:: yaml
+
+       ---
+       project: <opnfv-project-name>
+       project-type: <opnfv-project-type>
+       release-model: stable
+
+       branches:
+         - name: stable/<release>
+           location:
+             <project-repo>: <git-sha1>
+
+#. Modify the file, replacing the previous stable branch name with the
+   new release name, and the commit the branch will start at. For
+   example:
+
+   .. code-block:: yaml
+
+     branches:
+       - name: stable/fraser
+         location:
+           apex: <git-full-sha1>
+
+#. If your project contains multiple repositories, add them to the list
+   of branches. They can also be added later if more time is needed
+   before the stable branch window closes.
+
+   .. code-block:: yaml
+
+     branches:
+       - name: stable/fraser
+         location:
+           apex: <git-sha1>
+       - name: stable/fraser
+         location:
+           apex-puppet-tripleo: <git-sha1>
+
+#. Git add, commit, and git-review the changes. A job will be triggered
+   to verify the commit exists on the branch, and the yaml file follows
+   the scheme listed in ``releases/schema.yaml``
+
+#. Once the commit has been reviewed and merged by Releng, a job will
+   be triggered to create the stable branch Jenkins jobs under
+   ``jjb/``.
+
+
+Stable Release Tagging
+----------------------
+
+TBD
+
+Release File Fields
+-------------------
+
+The following is a description of fields in the Release file, which are
+verified by the scheme file at ``releases/schema.yaml``
+
+project
+  Project team in charge of the release.
+
+release-model
+  Release model the project follows.
+
+  One of: stable, non-release
+
+project-type
+  Classification of project within OPNFV.
+
+  One of: installer, feature, testing, tools, infra
+
+upstream
+  (Optional) Upstream OpenStack project assocated with this project.
+
+releases
+  List of released versions for the project.
+
+  version
+    Version of the release, must be in the format ``opnfv-X.Y.Z``.
+
+  location
+    Combination of repository and git hash to locate the release
+    version.
+
+    Example::
+
+        opnfv-project: f15d50c2009f1f865ac6f4171347940313727547
+
+branches
+   List of stable branches for projects following the ``stable`` release-model.
+
+   name
+     Stable branch name. Must start with the string ``stable/``
+
+   location
+     Same syntax as ``location`` under ``releases``
+
+release-notes
+   Link to release notes for the projects per-release.
+
+
+Scripts
+-------
+
+* ``create_branch.py -f <RELEASE_FILE>``
+
+  Create branches in Gerrit listed in the release file.
+
+  Must be ran from the root directory of the releng repository as the
+  release name is extracted from the subdirectory under ``releases/``
+
+  The Gerrit server can be changed by creating a ``~/releases.cfg``
+  file with the following content::
+
+    [gerrit]
+    url=http://gerrit.example.com
+
+  This will override the default configuration of using the OPNFV
+  Gerrit server at https://gerrit.opnfv.org, and is primarily used for
+  testing.
+
+* ``create_jobs.py -f <RELEASE_FILE>``
+
+  Modifies the jenkins job files for a project to add the stable branch
+  stream. Assumes the jenkins jobs are found in the releng repository
+  under ``jjb/<project>/``
+
+* ``verify_schema -s <SCHEMA_FILE> -y <YAML_FILE>``
+
+  Verifies the yaml file matches the specified jsonschema formatted
+  file. Used to verify the release files under ``releases/``