1 .. This work is licensed under a Creative Commons Attribution
2 .. 4.0 International License.
3 .. http://creativecommons.org/licenses/by/4.0
5 Using Policy Release scripts to make Policy Framework releases
6 ##############################################################
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>`_.
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.
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.
21 The following scripts are provided:
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
33 - generates a new commit or a patch on an existing commit on repositories, it is called when another script has
36 - gets and updates information from the checked out Policy Framework repos for the release process
38 - creates the artifact release yaml file for a release in the "releases" directory
40 - creates the docker release yaml file for a release in the "releases" directory
42 - generates the commits to perform a given phase of the Policy Framework release process
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
54 - updates the inter-repo references in Policy Framework POM files
56 The scripts have been verified to work on Ubuntu 20.04.3 and on MacOS Monterey 12.0.1.
59 On MacOS, GNU sed must be used. Download the 'gsed' command using homebrew
64 Set up the release scripts for use
65 ----------------------------------
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>`_.
70 #. Add the *<path_to_policy_parent>/integration/src/release_scripts* directory to your PATH
72 Check out a clean copy of the Policy Framework repos
73 ----------------------------------------------------
75 Check out the Policy Framework repos into a directory into the structure below:
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
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.
96 Common Arguments to Scripts
97 ===========================
99 The scripts take certain arguments and arguments are common over scripts
108 - the policy release data file to create, defaults to './pf_release_data.csv'
110 - Print help for the script
112 - JIRA issue ID in the format POLICY-nnnn
114 - the location of the policy framework repos on the file system, defaults to './'
116 - the policy repo to which to commit, such as 'policy/distribtuion'
118 Build the release data file
119 ===========================
121 Run the *getReleaseData.sh* script to build the release data file.
125 getReleaseData.sh -l policy_repo_location -d work_location/pf_release_data.csv
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*.
130 The contents of the data file is similar to the structure below:
134 :widths: 10 7 10 7 66
139 - Master Snapshot Version
151 - 'policy-jre-alpine':'policy-jdk-alpine':'policy-db-migrator'
177 * - policy/drools-pdp
187 * - policy/distribution
191 - 'policy-distribution'
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'
202 * - policy/drools-applications
208 The columns in the data file are described below.
217 - the policy framework repo
219 - the last version of the repo that has been released
220 * - Master Snapshot Version
221 - the current snapshot version of the repo
223 - the number of changed files on the snapshot version since the last release
225 - the docker images that are released from the repo as a ':' delimited list
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.
233 There are a number of phases in doing a release of the Policy Framework, which must be performed in the correct order.
235 Each phase roughly follows the steps below:
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
242 .. image:: images/RepoDependencies.png
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*.
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.
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 +-------+----------------------+-------------------------------------------------------------------------+