docs/system-attributes/release-scripts.rst

   1 .. This work is licensed under a  Creative Commons Attribution
   2 .. 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 Using Policy Release scripts to make Policy Framework releases
   6 ##############################################################
   7
   8 This page describes how to make a release of the Policy Framework using the Policy Framework release scripts. the
   9 scripts are available `in Github here <https://github.com/onap/policy-parent/tree/master/integration/src/release_scripts>`_.
  10
  11 The release scripts generate a data file that keeps track of the status of each repo as the release proceeds. The
  12 scripts use the data in the data file to automatically generate artifacts and commits for the releases process.
  13
  14 .. warning::
  15   The release scripts are an aid in the releae process and do help to apeed upthe work of doing a release. However they
  16   do NOT automate the release process, a high degree of manual work and supervision is still required to do a release.
  17
  18 The Scripts
  19 ===========
  20
  21 The following scripts are provided:
  22
  23 .. list-table::
  24    :widths: 15 85
  25    :header-rows: 1
  26
  27    * - Script
  28      - Description
  29    * - bumpSnapshots.sh
  30      - generate commits to bump the snapshot version and update references to snapshot references on any repos that
  31        need to be bumped or updated based on the data in the release data file
  32    * - generateCommit.sh
  33      - generates a new commit or a patch on an existing commit on repositories, it is called when another script has
  34        updated a repository
  35    * - getReleaseData.sh
  36      - gets and updates information from the checked out Policy Framework repos for the release process
  37    * - mkart.sh
  38      - creates the artifact release yaml file for a release in the "releases" directory
  39    * - mkdock.sh
  40      - creates the docker release yaml file for a release in the "releases" directory
  41    * - releasePhase.sh
  42      - generates the commits to perform a given phase of the Policy Framework release process
  43    * - releaseRepo.sh
  44      - release the specified repository by generating the release yaml file and the release commit, calls "mkArt.sh" and
  45        "generateCommit.sh" to release the repo
  46    * - releaseRepoImages.sh
  47      - release the docker images for the specified repository by generating the release yaml file and the release"
  48        commit, calls "mkDock.sh" and "generateCommit.sh" to release the images
  49    * - updateOomImages.sh
  50      - generate an OOM commit to update the versions of Policy Framework images in values.yaml files
  51    * - updateParentRef.sh
  52      - update the parent reference in a POM file
  53    * - updateRefs.sh
  54      - updates the inter-repo references in Policy Framework POM files
  55
  56 The scripts have been verified to work on Ubuntu 20.04.3 and on MacOS Monterey 12.0.1.
  57
  58 .. note::
  59     On MacOS, GNU sed must be used. Download the 'gsed' command using homebrew
  60
  61 Prerequisites
  62 =============
  63
  64 Set up the release scripts for use
  65 ----------------------------------
  66
  67 #. Check out the Policy Framework parent repo from the ONAP gerrit:
  68    `https://gerrit.onap.org/r/admin/repos/policy/parent <https://gerrit.onap.org/r/admin/repos/policy/parent>`_.
  69
  70 #. Add the *<path_to_policy_parent>/integration/src/release_scripts* directory to your PATH
  71
  72 Check out a clean copy of the Policy Framework repos
  73 ----------------------------------------------------
  74
  75 Check out the Policy Framework repos into a directory into the structure below:
  76
  77 .. code-block::
  78
  79     <path_to_repos>/policy/parent
  80     <path_to_repos>/policy/docker
  81     <path_to_repos>/policy/common
  82     <path_to_repos>/policy/models
  83     <path_to_repos>/policy/api
  84     <path_to_repos>/policy/pap
  85     <path_to_repos>/policy/apex-pdp
  86     <path_to_repos>/policy/drools-pdp
  87     <path_to_repos>/policy/xacml-pdp
  88     <path_to_repos>/policy/distribution
  89     <path_to_repos>/policy/clamp
  90     <path_to_repos>/policy/gui
  91     <path_to_repos>/policy/drools-applications
  92
  93 A script such as that described in the **Cloning All The Policy Repositories** section of the
  94 :ref:`policy-development-tools-label` page can be used to automatically clone the repos.
  95
  96 Common Arguments to Scripts
  97 ===========================
  98
  99 The scripts take certain arguments and arguments are common over scripts
 100
 101 .. list-table::
 102    :widths: 20 80
 103    :header-rows: 1
 104
 105    * - Argument
 106      - Description
 107    * - -d data-file
 108      - the policy release data file to create, defaults to './pf_release_data.csv'
 109    * - -h
 110      - Print help for the script
 111    * - -i issue-id
 112      - JIRA issue ID in the format POLICY-nnnn
 113    * - -l location
 114      - the location of the policy framework repos on the file system, defaults to './'
 115    * - -r repo
 116      - the policy repo to which to commit, such as 'policy/distribtuion'
 117
 118 Build the release data file
 119 ===========================
 120
 121 Run the *getReleaseData.sh* script to build the release data file.
 122
 123 .. code-block::
 124
 125     getReleaseData.sh -l policy_repo_location -d work_location/pf_release_data.csv
 126
 127 The command above examines the Policy Framework repositories in the directory *policy_repo_location* and creates a CSV
 128 file called pf_release_data.csv in the directory *work_location*.
 129
 130 The contents of the data file is similar to the structure below:
 131
 132
 133 .. list-table::
 134    :widths: 10 7 10 7 66
 135    :header-rows: 1
 136
 137    * - Repo
 138      - Last Tag Version
 139      - Master Snapshot Version
 140      - Changed Files
 141      - Docker Images
 142    * - policy/parent
 143      - 3.5.0
 144      - 3.5.1-SNAPSHOT
 145      - 10
 146      -
 147    * - policy/docker
 148      - 2.4.0
 149      - 2.4.1-SNAPSHOT
 150      - 4
 151      - 'policy-jre-alpine':'policy-jdk-alpine':'policy-db-migrator'
 152    * - policy/common
 153      - 1.10.0
 154      - 1.10.1-SNAPSHOT
 155      - 0
 156      -
 157    * - policy/models
 158      - 2.6.0
 159      - 2.6.1-SNAPSHOT
 160      - 0
 161      -
 162    * - policy/api
 163      - 2.6.0
 164      - 2.6.1-SNAPSHOT
 165      - 0
 166      - 'policy-api'
 167    * - policy/pap
 168      - 2.6.0
 169      - 2.6.1-SNAPSHOT
 170      - 66
 171      - 'policy-pap'
 172    * - policy/apex-pdp
 173      - 2.7.0
 174      - 2.7.1-SNAPSHOT
 175      - 3
 176      - 'policy-apex-pdp'
 177    * - policy/drools-pdp
 178      - 1.10.0
 179      - 1.10.1-SNAPSHOT
 180      - 0
 181      - 'policy-drools'
 182    * - policy/xacml-pdp
 183      - 2.6.0
 184      - 2.6.1-SNAPSHOT
 185      - 0
 186      - 'policy-xacml-pdp'
 187    * - policy/distribution
 188      - 2.7.0
 189      - 2.7.1-SNAPSHOT
 190      - 25
 191      - 'policy-distribution'
 192    * - policy/clamp
 193      - 6.2.0
 194      - 6.2.1-SNAPSHOT
 195      - 23
 196      - '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'
 197    * - policy/gui
 198      - 2.2.0
 199      - 2.2.1-SNAPSHOT
 200      - 16
 201      - 'policy-gui'
 202    * - policy/drools-applications
 203      - 1.10.0
 204      - 1.10.1-SNAPSHOT
 205      - 0
 206      - 'policy-pdpd-cl'
 207
 208 The columns in the data file are described below.
 209
 210 .. list-table::
 211    :widths: 20 80
 212    :header-rows: 1
 213
 214    * - Column
 215      - Description
 216    * - Repo
 217      - the policy framework repo
 218    * - Last Tag Version
 219      - the last version of the repo that has been released
 220    * - Master Snapshot Version
 221      - the current snapshot version of the repo
 222    * - Changed Files
 223      - the number of changed files on the snapshot version since the last release
 224    * - Docker Images
 225      - the docker images that are released from the repo as a ':'  delimited list
 226
 227 When you run the *getReleaseData.sh* script, it updates the current status of the release to the release data file. You
 228 will run this script many times during the release process as commits are merged and as the current status changes.
 229
 230 Doing a Release
 231 ===============
 232
 233 There are a number of phases in doing a release of the Policy Framework, which must be performed in the correct order.
 234
 235 Each phase roughly follows the steps below:
 236
 237 #. Run the *getReleaseData.sh* script to update the local release data CSV file
 238 #. Run the *releasePhase.sh* script to create the artifacts and generate the commits for a phase
 239 #. Use gerrit to drive the generated commits through the normal ONAP review process until the commits are merged
 240 #. Move onto the next phase
 241
 242 .. image:: images/RepoDependencies.png
 243    :width: 1000
 244
 245 The diagram above shows the dependency order of Policy Framework repos. Therefore, in the release process, the phases
 246 release the repos in order moving from left to right, staring with *policy/parent* and finishing with
 247 *policy/drools-applications*.
 248
 249
 250 The table below gives details of each phase in the release process. The *-l*, *-d*, and *-i* arguments on the
 251 *releasePhase.sh* script are omitted for brevity. Please specify those arguments to suit your local work setup.
 252
 253 +-------+----------------------+-------------------------------------------------------------------------+
 254 | Phase | Steps                | Description                                                             |
 255 +-------+----------------------+-------------------------------------------------------------------------+
 256 | 1     | getReleaseData.sh    | Update parent references in the parent pom.xml, submit commit to git,   |
 257 |       +----------------------+ and get the commit merged.                                              |
 258 |       | releasePhase.sh -p 1 |                                                                         |
 259 +-------+----------------------+-------------------------------------------------------------------------+
 260 | 2     | stage-release        | In Gerrit, run the *stage-release* magic word on the merged commit      |
 261 |       +----------------------+ created in phase 1. Then update your local data. Create the artifact    |
 262 |       | getReleaseData.sh    | artifact release yaml file in the *releases* directory, and submit the  |
 263 |       +----------------------+ commit to git. Then get the commit merged.                              |
 264 |       | releasePhase.sh -p 2 |                                                                         |
 265 +-------+----------------------+-------------------------------------------------------------------------+
 266
 267
 268
 269
 270
 271 End of Document