Andrea Campanella | 4dfe932 | 2022-05-10 12:40:10 +0200 | [diff] [blame] | 1 | VOLTHA Release process |
| 2 | ====================== |
| 3 | This document describes the technical steps of VOLTHA's release process. |
| 4 | The document assumes you are creating a release named voltha-X.Y, where X is the major release versio |
| 5 | and the y is the minor. |
| 6 | See versioning in the :doc:`releases documentation </overview/releases>` |
| 7 | |
| 8 | Code Freeze and pre-release testing |
| 9 | ----------------------------------- |
| 10 | |
| 11 | VOLTHA is released every 6 months. The suggested codefreeze is 3 weeks before release. |
| 12 | Code freeze means that no functionality is added, only bug fixes and tests can be added during the code freeze time. |
| 13 | Code freeze is announced during the TST meetings and enforced by the core contributors that have +2/merge access. |
| 14 | The 3 weeks of code freeze are used to stabilize the tests and prepare the components for the release. |
| 15 | |
| 16 | During code freeze the jenkins jobs test the latest code in master which, given the code freeze state, is the |
| 17 | release candidate (RC) for the release. |
| 18 | A release can be considered ready if the tests on Jenkins pass with no issue, both on hardware and bbsim jobs. |
| 19 | |
| 20 | Component releasing and Lazy Branching |
| 21 | -------------------------------------- |
| 22 | In VOLTHA for a release we release components (services) and lazy branch when/if needed. |
| 23 | Once a component (service) is ready to be released we increase the version in the VERSION file, |
| 24 | going from the -dev or released version x.y.z to either a higher number in minor version (y) or in bug version (z). |
| 25 | |
| 26 | To allow for future patches to go into the repo in a way that does not conflict with the patch version, |
| 27 | each component repo's VERSION file should have it's minor version increased in master. (ex: 1.1.X to 1.2.0-dev, |
| 28 | so future 1.1.X+1 component release can easily be created for the released VOLTHA version). |
| 29 | |
Joey Armstrong | d24a112 | 2023-01-04 09:34:46 -0500 | [diff] [blame] | 30 | The same should be done on Helm charts in the chart repos post release, but the versions there shouldn't include a |
Andrea Campanella | 4dfe932 | 2022-05-10 12:40:10 +0200 | [diff] [blame] | 31 | -dev suffix because chart publishing requires that every new chart version be unique and using un-suffixed SemVer is a |
| 32 | better release numbering pattern. |
| 33 | |
| 34 | If a repository is branched the `.gitreview` file needs to be changed, adding `defaultorigin=voltha-X.Y` at the end. |
| 35 | |
| 36 | .. note:: |
| 37 | Given the dependency of the containers on the protos and the library, if the voltha-protos and/or voltha-lib-go or |
| 38 | omci-lib-go need to be released, it should be done first and then updated in the components: |
| 39 | |
| 40 | - release `voltha-proto` |
| 41 | - update `voltha-lib-go` and release it |
| 42 | - change the protos and lib-go versions in the components (in `go.mod`) |
| 43 | - issue `make mod-update` |
| 44 | - release the component |
| 45 | |
| 46 | |
| 47 | Every repository that need releasing is listed here. |
| 48 | |
| 49 | Services: |
| 50 | |
| 51 | - `VOLTHA Core <https://github.com/opencord/voltha-go>`_ |
| 52 | - `OpenFlow Agent <https://github.com/opencord/ofagent-go>`_ |
| 53 | - `Openonu Adapter <https://github.com/opencord/voltha-openonu-adapter-go>`_ |
| 54 | - `Openolt Adapter <https://github.com/opencord/voltha-openolt-adapter>`_ |
| 55 | - `Openolt Agent <https://github.com/opencord/openolt>`_ |
| 56 | - `ONOS controller <https://github.com/opencord/voltha-onos>`_ (Note, only do it after releasing all the apps below) |
| 57 | - `BBSIM <https://github.com/opencord/bbsim>`_ |
| 58 | - `BBSIM Sadis Server <https://github.com/opencord/bbsim-sadis-server>`_ |
| 59 | |
| 60 | Libraries and APIs: |
| 61 | |
| 62 | - `VOLTHA protos <https://github.com/opencord/voltha-protos>`_ |
| 63 | - `VOLTHA Library in Go <https://github.com/opencord/voltha-lib-go>`_ |
| 64 | - `OMCI Library in GO <https://github.com/opencord/omci-lib-go>`_ |
| 65 | |
| 66 | Tools: |
| 67 | |
| 68 | - `voltctl <https://github.com/opencord/voltctl>`_ |
| 69 | |
| 70 | Configuration: |
| 71 | |
| 72 | - `pod-configs <https://github.com/opencord/pod-configs>`_ |
| 73 | |
| 74 | ONOS Apps |
| 75 | ^^^^^^^^^ |
| 76 | |
| 77 | The ONOS Apps need to be released in a different manner. |
| 78 | |
| 79 | There is a Jenkins job to release ONOS app: https://jenkins.opencord.org/job/onos-app-release. |
| 80 | It requires to be triggered with specific parameters, as an example you can check the latest job in that pipeline. |
| 81 | |
| 82 | 1. Build with parameters: use the name of the repo (not of the app itself) |
| 83 | 2. Wait for build to complete |
| 84 | 3. Merge the patches on gerrit https://gerrit.opencord.org/q/owner:do-not-reply%2540opennetworking.org |
Joey Armstrong | 56334fc | 2023-01-15 22:53:19 -0500 | [diff] [blame] | 85 | |
| 86 | - Two pull requests are created modifying pom.xml. |
| 87 | - Approve patch one (-SNAPSHOT: no) to initiate a release build. |
| 88 | - Approve patch two (-SNAPSHOT: yes) to revert pom.xml to a non-release version. |
| 89 | |
| 90 | 4. Approval and merge will trigger a `jenkins job <https://jenkins.opencord.org/job/maven-publish_sadis/>`_ that publish |
| 91 | an artifact into the staging repo on `sonatype <https://oss.sonatype.org>`_. From there the artifact will need |
| 92 | to be released into maven central. |
| 93 | |
Joey Armstrong | f713d7f | 2023-02-23 06:06:49 -0500 | [diff] [blame] | 94 | - Login into the sonatype server (for username and password contact michelle@opennetworking.org) |
Joey Armstrong | 56334fc | 2023-01-15 22:53:19 -0500 | [diff] [blame] | 95 | - search for org.opencord |
| 96 | - Select the app you want to release and click "all versions" |
| 97 | - Click on "Staging repositories" (in the left side navigation) |
| 98 | - In the top right search for last part of the app name (eg: olt) |
| 99 | - Click release (top left bar, small button) |
| 100 | |
| 101 | 5. Wait until the artifacts are published |
| 102 | |
| 103 | - https://search.maven.org/search?q=g:org.opencord |
| 104 | - https://search.maven.org/artifact/org.opencord/dhcpl2relay/2.9.0/pom |
| 105 | |
| 106 | 6. Iterate through apps: |
| 107 | |
| 108 | - Modify pom.xml and dependencies.xml |
| 109 | - Update version string for all released dependencies. |
| 110 | |
Joey Armstrong | f713d7f | 2023-02-23 06:06:49 -0500 | [diff] [blame] | 111 | 7. Start over with the next app |
Andrea Campanella | 4dfe932 | 2022-05-10 12:40:10 +0200 | [diff] [blame] | 112 | |
| 113 | .. note:: |
Joey Armstrong | f713d7f | 2023-02-23 06:06:49 -0500 | [diff] [blame] | 114 | Given component inter dependencies, ONOS apps need to be released in order: |
Andrea Campanella | 4dfe932 | 2022-05-10 12:40:10 +0200 | [diff] [blame] | 115 | |
| 116 | 1. sadis |
| 117 | 2. olt, aaa, dhcpl2relay, mcast, igmpproxy, maclearning |
| 118 | 3. bng, PPPoE |
| 119 | 4. kafka |
| 120 | |
| 121 | ONOS APPs: |
| 122 | |
| 123 | - `AAA <https://github.com/opencord/aaa>`_ |
| 124 | - `BNG <https://github.com/opencord/bng>`_ |
| 125 | - `DHCP L2 Relay <https://github.com/opencord/dhcpl2relay>`_ |
| 126 | - `IGMPProxy <https://github.com/opencord/igmpproxy>`_ |
| 127 | - `Kafka <https://github.com/opencord/kafka-onos>`_ |
| 128 | - `Mac Learning <https://github.com/opencord/mac-learning>`_ |
| 129 | - `Multicast <https://github.com/opencord/mcast>`_ |
| 130 | - `OLT <https://github.com/opencord/olt>`_ |
| 131 | - `OLT Topology <https://github.com/opencord/olttopology>`_ |
| 132 | - `PPPoE Agent <https://github.com/opencord/pppoeagent>`_ |
| 133 | - `Sadis <https://github.com/opencord/sadis>`_ |
| 134 | |
| 135 | |
Andrea Campanella | 4dfe932 | 2022-05-10 12:40:10 +0200 | [diff] [blame] | 136 | Creating the release |
| 137 | -------------------- |
| 138 | |
| 139 | Once the components have been tested and the release is considered ready there are 3 more elements that need to be |
| 140 | tagged: |
| 141 | |
| 142 | - `VOLTHA Helm Charts <https://github.com/opencord/voltha-helm-charts>`_ |
| 143 | - `VOLTHA System Tests <https://github.com/opencord/voltha-system-tests>`_ |
| 144 | - `VOLTHA docs <https://github.com/opencord/voltha-docs>`_ |
| 145 | |
| 146 | These 3 repos are the only ones that receive a X.Y.Z tag. Other repos that contain individual |
| 147 | components have their own versioning/release cadence, driven by SemVer. |
| 148 | |
| 149 | Helm Charts |
| 150 | ^^^^^^^^^^^ |
| 151 | |
| 152 | The official action of creating the voltha-X.Y release is releasing the voltha helm chart, and adapter charts |
| 153 | with version:X.Y.Z (e.g. 2.10.0) specified in Chart.yaml within the voltha-helm-charts repo, and within the VERSION |
| 154 | file in that repo. |
| 155 | A branch named voltha-X.Y needs to be created on the voltha-helm-charts repo. |
| 156 | The helm charts repo overall VERSION should also be incremented to the next minor version (X.Y+1-dev), so all X.Y.Z |
| 157 | releases of the overall charts repo will happen on the voltha-X.Y branch. |
| 158 | |
| 159 | Voltha-system-tests |
| 160 | ^^^^^^^^^^^^^^^^^^^ |
| 161 | Accompanying tests for voltha-X.Y are created by creating a branch created named voltha-X.Y on the voltha-system-tests |
| 162 | repo and creating a tag X.Y.Z on that branch. |
| 163 | |
| 164 | Documentation and Release Notes |
| 165 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 166 | Release notes for the voltha-X.Y release are created and added to the voltha-docs repo. Please follow the template of |
Joey Armstrong | 449ce7a | 2023-07-18 18:32:24 -0400 | [diff] [blame] | 167 | past releases, an :doc:`example <voltha_releases/voltha_2.12.rst>` |
Andrea Campanella | 4dfe932 | 2022-05-10 12:40:10 +0200 | [diff] [blame] | 168 | |
| 169 | Also, if needed a voltha-X.Y branch is created on docs repo. These release notes also contain all the |
| 170 | versions of components that will be released, and may be updated during the final QA process. |
| 171 | At release we create a tag X.Y.Z in the VERSION file. |
| 172 | |
| 173 | CI-Management |
| 174 | ^^^^^^^^^^^^^ |
| 175 | In the `Ci management <https://github.com/opencord/ci-management>`_ repository create the /voltha-x.y.z folder and copy the /master repos |
| 176 | Testing CI jobs should be created that check out the voltha-X.Y branch of the voltha-system-tests repo, testing the |
| 177 | charts as checked out with the voltha-X.Y tag of voltha-helm-charts. |
| 178 | |
| 179 | |
| 180 | Release support and bug-fixing |
| 181 | ------------------------------ |
| 182 | |
| 183 | What changes can be brought into the X.Y.Z branch? |
| 184 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 185 | Has to be a bug or non-code fix. |
| 186 | |
| 187 | Add a Jira item with type Bug, tag against VOLTHA vX.Y |
| 188 | Discuss on the Voltha mailing list, or in all-Voltha meeting, get consensus on whether should be brought to X.Y.z |
| 189 | Documentation or other non-code updates are also acceptable |
| 190 | |
| 191 | What is a bug? Not a new feature! |
| 192 | Anything that causes a functional regression test (Robot tests) to fail |
| 193 | Severe issue (causes data loss or crash), or frequently occurring -> add to X.Y |
| 194 | Issues that are merely annoying and don't cause data loss or a crash, or are very infrequently occurring -> may |
| 195 | wait for next release |
| 196 | |
| 197 | WHen a bug is found please add to tests both on the released version and the master branch, if tests don't cover |
| 198 | the bug. Add to Robot tests for integration-related issues, to Unit tests for code-level or functional issues. |
| 199 | |
| 200 | Update/Fixes to the released version |
| 201 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 202 | This section shows how to create minor releases on the X.Y.Z branch when a bug fix is required. |
| 203 | |
| 204 | If a fix is needed to the helm charts: |
| 205 | |
| 206 | - Make the fix on the master branch of voltha-helm-charts (assuming that it is required in both places). |
| 207 | - After the master tests pass, manually cherry-pick the fix to the voltha-X.Y branch (the Chart version would be |
| 208 | different, requiring the manual step). |
| 209 | - Cherry-picked patchsets on that branch will be checked by the voltha-X.Y branch of tests. |
| 210 | - When it passes, submitting the change will make a new X.Y.Z release |
| 211 | - Update the documentation to reflect the chart changes, a description of the changes made, and increment the tag |
| 212 | on the docs from X.Y.Z to X.Y.Z+1, to reflect the patch change. |
| 213 | - If all the charts are updated and working correctly, create a new charts point release by increasing the |
| 214 | X.Y.Z VERSION file in the voltha-helm-charts repo. The versions need to be updated in the voltha-docs repo, |
| 215 | which needs to be tagged as well, thus releasing it. |
| 216 | |
| 217 | If a fix is needed to the components/containers that are included by the helm charts: |
| 218 | |
| 219 | - Develop a fix to the issue on the master branch, get it approved after passing master tests. |
Joey Armstrong | d24a112 | 2023-01-04 09:34:46 -0500 | [diff] [blame] | 220 | - Manually cherry-pick to the voltha-X.Y branch of the component (create one if needed) |
Andrea Campanella | 4dfe932 | 2022-05-10 12:40:10 +0200 | [diff] [blame] | 221 | - incrementing the patch version in the VERSION file, |
| 222 | - test with the voltha-X.Y version of voltha-system-tests and helm charts. |
| 223 | - Update helm charts and go through the helm chart update process above. |
| 224 | - Update the voltha-docs with the right version of the component. |
| 225 | |
| 226 | If a fix is needed to the ONOS apps: |
| 227 | |
| 228 | - Create a branch here https://gerrit.opencord.org/plugins/gitiles/olt/+/refs/heads/olt-4.1 |
| 229 | - then `Git checkout -b <branch-name> opencord/<version>` |
| 230 | - Then push a commit changing to `.1-SNAPSHOT` more (see e.g. https://gerrit.opencord.org/c/igmpproxy/+/19589) |
| 231 | - Then push you changes (e.g. https://gerrit.opencord.org/c/igmpproxy/+/19590) |
| 232 | - Then release as per the process above. |
Joey Armstrong | 56334fc | 2023-01-15 22:53:19 -0500 | [diff] [blame] | 233 | |
| 234 | See Also |
| 235 | ======== |
| 236 | - `VOLTHA Release Process <https://docs.voltha.org/master/overview/release_process.html?highlight=charts%20yaml>`_ |
| 237 | - `release_notes: Release Process <https://docs.voltha.org/master/release_notes/release_process.html>`_ |
| 238 | - `VOLTHA and ONOS Software Update Procedure <https://docs.voltha.org/master/operations/software-upgrade.html?highlight=set%20global%20image>`_ |
| 239 | - `Helm Chart Deployment <https://docs.voltha.org/master/voltha-helm-charts/README.html?highlight=voltctl>`_ |