Docs: New releasing guide

New guide on how to perform the release process.

Change-Id: I2935f3644de89deb5b45cf84e63b8f048ab26931
Signed-off-by: Patrick Brady <patrick.brady@att.com>
Issue-ID: APPC-1872

diff --git a/docs/APPC Deployment Guidelines/APPC Release Guidelines.rst b/docs/APPC Deployment Guidelines/APPC Release Guidelines.rst
new file mode 100644 (file)
index 0000000..2b2f757
--- /dev/null
+++ b/docs/APPC Deployment Guidelines/APPC Release Guidelines.rst
@@ -0,0 +1,162 @@
+.. ============LICENSE_START==========================================
+.. ===================================================================
+.. Copyright © 2020 AT&T Intellectual Property. All rights reserved.
+.. ===================================================================
+.. Licensed under the Creative Commons License, Attribution 4.0 Intl.  (the "License");
+.. you may not use this documentation except in compliance with the License.
+.. You may obtain a copy of the License at
+.. 
+..  https://creativecommons.org/licenses/by/4.0/
+.. 
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ============LICENSE_END============================================
+
+=============
+Building APPC
+=============
+
+Introduction
+============
+
+This document will go over how to perform an official APPC release on ONAP. This document only applies to PTLs and
+committers, since certain permissions are required to perform an official release.
+
+Releasing the APPC Parent Files
+===============================
+
+First we will release the APPC parent files, since they are used by the main APPC project. Release version for the
+parent files start with a "2". For example, "2.7.1". This keeps the parent version differentiated from the other APPC
+versions, which start with a "1".
+
+1. Go to the appc/parent Gerrit page.
+2. Find the most recent gerrit review that has been merged. Leave a comment on this review with the words:
+   "stage-maven-release". This will trigger the staging job.
+3. Check the Jenkins job `appc-parent-maven-stage-master <https://jenkins.onap.org/view/appc/job/
+   appc-parent-maven-stage-master/>`_. You can monitor the staging build job from here.
+4. Once the Jenkins build job is finished, note the number of that build job.
+5. Open your local copy of the appc/parent repository. Go to the "releases" directory.
+6. Copy one of the existing release files in that directory. Rename the new file with the version number that you are
+   releasing.
+7. Open the new file. Update the "version:" with the version number that you are releasing. Update the "log_dir:" with
+   the Jenkins job number from step 4.
+8. Commit and push this new file to Gerrit. You can use a commit title like "Add 2.7.1 release file" or something
+   similar.
+9. Once this change is merged in Gerrit, a new release for org.onap.appc.parent will be created in Nexus.
+
+Releasing the Main APPC Project
+===============================
+
+1. First, references to the appc parent files need to be set to match the version of the parent files that you just
+   released, rather than a snapshot version. You can search for the text "org.onap.appc.parent" in all of the pom.xml
+   files in the appc repository. Perform a find/replace on entire version tag "<version>...</version>" for the parent
+   file in order to update the APPC parent version.
+2. Commit and push this change to Gerrit. Merge the change.
+3. Once the merge is complete, leave a comment on the review with the text "stage-maven-release". (This is assuming that
+   your parent change was the lastest change merged, if it was not, leave the "stage-maven-release" comment on
+   whichever review was most recently merged).
+4. Check the Jenkins job `appc-maven-stage-master <https://jenkins.onap.org/view/appc/job/appc-maven-stage-master/>`_.
+   You can monitor the staging build job from here.
+5. Once the Jenkins build job is finished, note the number of that build job.
+6. Open your local copy of the appc repository. Go to the "releases" directory.
+7. Copy one of the existing release files in that directory. Rename the new file with the version number that you are
+   releasing.
+8. Open the new file. Update the "version:" with the version number that you are releasing. Update the "log_dir:" with
+   the Jenkins job number from step 4.
+9. Commit and push this new file to Gerrit. You can use a commit title like "Add 1.7.1 release file" or something
+   similar.
+10. Once this change is merged in Gerrit, a new release for org.onap.appc will be created in Nexus. 
+
+Releasing the APPC CDT Project
+==============================
+
+1. Go to the appc/cdt Gerrit page.
+2. Find the most recent gerrit review that has been merged. Leave a comment on this review with the words:
+   "stage-maven-release". This will trigger the staging job.
+3. Check the Jenkins job `appc-cdt-maven-stage-master <https://jenkins.onap.org/view/appc/job/
+   appc-cdt-maven-stage-master/>`_. You can monitor the staging build job from here.
+4. Once the Jenkins build job is finished, note the number of that build job.
+5. Open your local copy of the appc/cdt repository. Go to the "releases" directory.
+6. Copy one of the existing release files in that directory. Rename the new file with the version number that you are
+   releasing.
+7. Open the new file. Update the "version:" with the version number that you are releasing. Update the "log_dir:" with
+   the Jenkins job number from step 4.
+8. Commit and push this new file to Gerrit. You can use a commit title like "Add 1.7.1 release file" or something
+   similar.
+9. Once this change is merged in Gerrit, a new release for org.onap.appc.cdt will be created in Nexus.
+
+Releasing the APPC Docker Images
+================================
+
+Update the APPC Artifact Download Versions
+------------------------------------------
+
+The following operations should be performed in your local copy of the appc/deployment repository.
+
+1. Open the "installation/appc/pom.xml" file.
+
+   a. Set the "<appc.release.version>" property to the version of APPC that you just released.
+   b. Set the "<appc.cdt.version>" property to the version of APPC CDT that you just released.
+
+2. Open the "cdt/pom.xml" file.
+
+   a. Set the "<appc.release.version>" to the version of APPC CDT that you just released.
+
+3. Open the "installation/appc/src/main/docker/Dockerfile" file.
+
+   a. Make sure that the ccsdk image version listed on the "FROM" line is set to the released (non snapshot) version of
+      ccsdk that you want to use to build APPC on.
+
+4. Commit and push these changes to Gerrit. Merge the change, once the verify job completes.
+
+Prepare to Release the Docker Images
+------------------------------------
+
+1. Go to the appc/deployment Gerrit page.
+2. Find the most recent gerrit review that has been merged. Leave a comment on this review with the words:
+   "stage-docker-release". This will trigger the staging job.
+3. Check the Jenkins job `appc-deployment-maven-docker-stage-master <https://jenkins.onap.org/view/appc/job/
+   appc-deployment-maven-docker-stage-master/>`_. You can monitor the docker staging build job from here.
+4. Once the Jenkins build job is finished, note the number of that build job.
+5. Open the "Console Output" for the build job. You may need to click the "Full Log" link to see the whole log.
+6. Search the page for the text "tag 2". Copy the tag text (this should be the tag with the date time stamp).
+
+Check the Docker Images Before Release
+--------------------------------------
+
+Optionally, you can download the staged Docker images, and make sure everything is correct, before releasing them.
+
+You can use the Docker tag you copied from Jenkins (from step 6 of the "Prepare to Release the Docker Images" section)
+and download this Docker image:
+
+.. code:: bash
+
+  docker pull nexus3.onap.org:10001/onap/appc-image:<image tag from Jenkins>
+  docker pull nexus3.onap.org:10001/onap/appc-cdt-image:<image tag from Jenkins>
+
+Release the Docker Images
+-------------------------
+
+1. Open your local copy of the appc/deployment repository. Go to the "releases" directory.
+2. Copy one of the existing release files in that directory. Rename the new file with the version number that you are
+   releasing, followed by the text "-container".
+3. Open the new file.
+
+   a. Update the "container_release_tag:" with the version number that you are releasing.
+   b. Update the "log_dir:" with the Jenkins appc-deployment-maven-docker-stage-master job number that built the staging
+      images (from step 4 of the "Prepare to Release the Docker Images" section).
+   c. Update the "ref:" with the git commit id of the Gerrit review where you made the "stage-docker-release" comment.
+      (from step 2 of the "Prepare to Release the Docker Images" section).
+   d. Under the "containers:" section, update both "version:" with the image tag from Jenkins (from step 6 of the
+      "Prepare to Release the Docker Images" section).
+
+4. Commit and push this new file to Gerrit. You can use a commit title like "Add 1.7.1 container release file" or
+   something similar.
+5. Once this change is merged in Gerrit, the appc-image and appc-cdt-image Docker images will be released in Nexus 3
+
+
+
+