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