Release script documentation, first commit

First part of the release script documentaiton

Issue-ID: POLICY-3835
Change-Id: I091904de34c66a1096c46a2d7a96364fc1f0484d
Signed-off-by: liamfallon <liam.fallon@est.tech>

3 files changed, 272 insertions, 0 deletions

diff --git a/docs/system-attributes/images/RepoDependencies.png b/docs/system-attributes/images/RepoDependencies.png
new file mode 100644
index 00000000..5ba4f3b9
--- /dev/null
+++ b/docs/system-attributes/images/RepoDependencies.png
diff --git a/docs/system-attributes/release-scripts.rst b/docs/system-attributes/release-scripts.rst
new file mode 100644
index 00000000..bc466bbf
--- /dev/null
+++ b/docs/system-attributes/release-scripts.rst
@@ -0,0 +1,271 @@
+.. This work is licensed under a  Creative Commons Attribution
+.. 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Using Policy Release scripts to make Policy Framework releases
+##############################################################
+
+This page describes how to make a release of the Policy Framework using the Policy Framework release scripts. the
+scripts are available `in Github here <https://github.com/onap/policy-parent/tree/master/integration/src/release_scripts>`_.
+
+The release scripts generate a data file that keeps track of the status of each repo as the release proceeds. The
+scripts use the data in the data file to automatically generate artifacts and commits for the releases process.
+
+.. warning::
+  The release scripts are an aid in the releae process and do help to apeed upthe work of doing a release. However they
+  do NOT automate the release process, a high degree of manual work and supervision is still required to do a release.
+
+The Scripts
+===========
+
+The following scripts are provided:
+
+.. list-table::
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Script
+     - Description
+   * - bumpSnapshots.sh
+     - generate commits to bump the snapshot version and update references to snapshot references on any repos that
+       need to be bumped or updated based on the data in the release data file
+   * - generateCommit.sh
+     - generates a new commit or a patch on an existing commit on repositories, it is called when another script has
+       updated a repository
+   * - getReleaseData.sh
+     - gets and updates information from the checked out Policy Framework repos for the release process
+   * - mkart.sh
+     - creates the artifact release yaml file for a release in the "releases" directory
+   * - mkdock.sh
+     - creates the docker release yaml file for a release in the "releases" directory
+   * - releasePhase.sh
+     - generates the commits to perform a given phase of the Policy Framework release process
+   * - releaseRepo.sh
+     - release the specified repository by generating the release yaml file and the release commit, calls "mkArt.sh" and
+       "generateCommit.sh" to release the repo
+   * - releaseRepoImages.sh
+     - release the docker images for the specified repository by generating the release yaml file and the release"
+       commit, calls "mkDock.sh" and "generateCommit.sh" to release the images
+   * - updateOomImages.sh
+     - generate an OOM commit to update the versions of Policy Framework images in values.yaml files
+   * - updateParentRef.sh
+     - update the parent reference in a POM file
+   * - updateRefs.sh
+     - updates the inter-repo references in Policy Framework POM files
+
+The scripts have been verified to work on Ubuntu 20.04.3 and on MacOS Monterey 12.0.1.
+
+.. note::
+    On MacOS, GNU sed must be used. Download the 'gsed' command using homebrew
+
+Prerequisites
+=============
+
+Set up the release scripts for use
+----------------------------------
+
+#. Check out the Policy Framework parent repo from the ONAP gerrit:
+   `https://gerrit.onap.org/r/admin/repos/policy/parent <https://gerrit.onap.org/r/admin/repos/policy/parent>`_.
+
+#. Add the *<path_to_policy_parent>/integration/src/release_scripts* directory to your PATH
+
+Check out a clean copy of the Policy Framework repos
+----------------------------------------------------
+
+Check out the Policy Framework repos into a directory into the structure below:
+
+.. code-block::
+
+    <path_to_repos>/policy/parent
+    <path_to_repos>/policy/docker
+    <path_to_repos>/policy/common
+    <path_to_repos>/policy/models
+    <path_to_repos>/policy/api
+    <path_to_repos>/policy/pap
+    <path_to_repos>/policy/apex-pdp
+    <path_to_repos>/policy/drools-pdp
+    <path_to_repos>/policy/xacml-pdp
+    <path_to_repos>/policy/distribution
+    <path_to_repos>/policy/clamp
+    <path_to_repos>/policy/gui
+    <path_to_repos>/policy/drools-applications
+
+A script such as that described in the **Cloning All The Policy Repositories** section of the
+:ref:`policy-development-tools-label` page can be used to automatically clone the repos.
+
+Common Arguments to Scripts
+===========================
+
+The scripts take certain arguments and arguments are common over scripts
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Argument
+     - Description
+   * - -d data-file
+     - the policy release data file to create, defaults to './pf_release_data.csv'
+   * - -h
+     - Print help for the script
+   * - -i issue-id
+     - JIRA issue ID in the format POLICY-nnnn
+   * - -l location
+     - the location of the policy framework repos on the file system, defaults to './'
+   * - -r repo
+     - the policy repo to which to commit, such as 'policy/distribtuion'
+
+Build the release data file
+===========================
+
+Run the *getReleaseData.sh* script to build the release data file.
+
+.. code-block::
+
+    getReleaseData.sh -l policy_repo_location -d work_location/pf_release_data.csv
+
+The command above examines the Policy Framework repositories in the directory *policy_repo_location* and creates a CSV
+file called pf_release_data.csv in the directory *work_location*.
+
+The contents of the data file is similar to the structure below:
+
+
+.. list-table::
+   :widths: 10 7 10 7 66
+   :header-rows: 1
+
+   * - Repo
+     - Last Tag Version
+     - Master Snapshot Version
+     - Changed Files
+     - Docker Images
+   * - policy/parent
+     - 3.5.0
+     - 3.5.1-SNAPSHOT
+     - 10
+     -
+   * - policy/docker
+     - 2.4.0
+     - 2.4.1-SNAPSHOT
+     - 4
+     - 'policy-jre-alpine':'policy-jdk-alpine':'policy-db-migrator'
+   * - policy/common
+     - 1.10.0
+     - 1.10.1-SNAPSHOT
+     - 0
+     -
+   * - policy/models
+     - 2.6.0
+     - 2.6.1-SNAPSHOT
+     - 0
+     -
+   * - policy/api
+     - 2.6.0
+     - 2.6.1-SNAPSHOT
+     - 0
+     - 'policy-api'
+   * - policy/pap
+     - 2.6.0
+     - 2.6.1-SNAPSHOT
+     - 66
+     - 'policy-pap'
+   * - policy/apex-pdp
+     - 2.7.0
+     - 2.7.1-SNAPSHOT
+     - 3
+     - 'policy-apex-pdp'
+   * - policy/drools-pdp
+     - 1.10.0
+     - 1.10.1-SNAPSHOT
+     - 0
+     - 'policy-drools'
+   * - policy/xacml-pdp
+     - 2.6.0
+     - 2.6.1-SNAPSHOT
+     - 0
+     - 'policy-xacml-pdp'
+   * - policy/distribution
+     - 2.7.0
+     - 2.7.1-SNAPSHOT
+     - 25
+     - 'policy-distribution'
+   * - policy/clamp
+     - 6.2.0
+     - 6.2.1-SNAPSHOT
+     - 23
+     - 'policy-clamp-backend':'policy-clamp-frontend':'policy-clamp-cl-pf-ppnt':'policy-clamp-cl-k8s-ppnt':'policy-clamp-cl-http-ppnt':'policy-clamp-cl-runtime'
+   * - policy/gui
+     - 2.2.0
+     - 2.2.1-SNAPSHOT
+     - 16
+     - 'policy-gui'
+   * - policy/drools-applications
+     - 1.10.0
+     - 1.10.1-SNAPSHOT
+     - 0
+     - 'policy-pdpd-cl'
+
+The columns in the data file are described below.
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Column
+     - Description
+   * - Repo
+     - the policy framework repo
+   * - Last Tag Version
+     - the last version of the repo that has been released
+   * - Master Snapshot Version
+     - the current snapshot version of the repo
+   * - Changed Files
+     - the number of changed files on the snapshot version since the last release
+   * - Docker Images
+     - the docker images that are released from the repo as a ':'  delimited list
+
+When you run the *getReleaseData.sh* script, it updates the current status of the release to the release data file. You
+will run this script many times during the release process as commits are merged and as the current status changes.
+
+Doing a Release
+===============
+
+There are a number of phases in doing a release of the Policy Framework, which must be performed in the correct order.
+
+Each phase roughly follows the steps below:
+
+#. Run the *getReleaseData.sh* script to update the local release data CSV file
+#. Run the *releasePhase.sh* script to create the artifacts and generate the commits for a phase
+#. Use gerrit to drive the generated commits through the normal ONAP review process until the commits are merged
+#. Move onto the next phase
+
+.. image:: images/RepoDependencies.png
+   :width: 1000
+
+The diagram above shows the dependency order of Policy Framework repos. Therefore, in the release process, the phases
+release the repos in order moving from left to right, staring with *policy/parent* and finishing with
+*policy/drools-applications*.
+
+
+The table below gives details of each phase in the release process. The *-l*, *-d*, and *-i* arguments on the
+*releasePhase.sh* script are omitted for brevity. Please specify those arguments to suit your local work setup.
+
++-------+----------------------+-------------------------------------------------------------------------+
+| Phase | Steps                | Description                                                             |
++-------+----------------------+-------------------------------------------------------------------------+
+| 1     | getReleaseData.sh    | Update parent references in the parent pom.xml, submit commit to git,   |
+|       +----------------------+ and get the commit merged.                                              |
+|       | releasePhase.sh -p 1 |                                                                         |
++-------+----------------------+-------------------------------------------------------------------------+
+| 2     | stage-release        | In Gerrit, run the *stage-release* magic word on the merged commit      |
+|       +----------------------+ created in phase 1. Then update your local data. Create the artifact    |
+|       | getReleaseData.sh    | artifact release yaml file in the *releases* directory, and submit the  |
+|       +----------------------+ commit to git. Then get the commit merged.                              |
+|       | releasePhase.sh -p 2 |                                                                         |
++-------+----------------------+-------------------------------------------------------------------------+
+
+
+
+
+
+End of Document
diff --git a/docs/system-attributes/system-attributes.rst b/docs/system-attributes/system-attributes.rst
index 7438c204..854c1d50 100644
--- a/docs/system-attributes/system-attributes.rst
+++ b/docs/system-attributes/system-attributes.rst
@@ -9,3 +9,4 @@ System Attributes: Handling, Integration, and Management of the Policy Framework
    :maxdepth: 1
 
    policy-db-migrator
+   release-scripts