.. 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 `_. 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 `_. #. Add the */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:: /policy/parent /policy/docker /policy/common /policy/models /policy/api /policy/pap /policy/apex-pdp /policy/drools-pdp /policy/xacml-pdp /policy/distribution /policy/clamp /policy/gui /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