blob: 45686eb615236b224e54f8c8a18f3e68fe167bcc [file] [log] [blame]
Andrea Campanella4dfe9322022-05-10 12:40:10 +02001VOLTHA Release process
2======================
3This document describes the technical steps of VOLTHA's release process.
4The document assumes you are creating a release named voltha-X.Y, where X is the major release versio
5and the y is the minor.
6See versioning in the :doc:`releases documentation </overview/releases>`
7
8Code Freeze and pre-release testing
9-----------------------------------
10
11VOLTHA is released every 6 months. The suggested codefreeze is 3 weeks before release.
12Code freeze means that no functionality is added, only bug fixes and tests can be added during the code freeze time.
13Code freeze is announced during the TST meetings and enforced by the core contributors that have +2/merge access.
14The 3 weeks of code freeze are used to stabilize the tests and prepare the components for the release.
15
16During code freeze the jenkins jobs test the latest code in master which, given the code freeze state, is the
17release candidate (RC) for the release.
18A release can be considered ready if the tests on Jenkins pass with no issue, both on hardware and bbsim jobs.
19
20Component releasing and Lazy Branching
21--------------------------------------
22In VOLTHA for a release we release components (services) and lazy branch when/if needed.
23Once a component (service) is ready to be released we increase the version in the VERSION file,
24going from the -dev or released version x.y.z to either a higher number in minor version (y) or in bug version (z).
25
26To allow for future patches to go into the repo in a way that does not conflict with the patch version,
27each component repo's VERSION file should have it's minor version increased in master. (ex: 1.1.X to 1.2.0-dev,
28so future 1.1.X+1 component release can easily be created for the released VOLTHA version).
29
Joey Armstrongd24a1122023-01-04 09:34:46 -050030The 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 +020031-dev suffix because chart publishing requires that every new chart version be unique and using un-suffixed SemVer is a
32better release numbering pattern.
33
34If 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
47Every repository that need releasing is listed here.
48
49Services:
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
60Libraries 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
66Tools:
67
68- `voltctl <https://github.com/opencord/voltctl>`_
69
70Configuration:
71
72- `pod-configs <https://github.com/opencord/pod-configs>`_
73
74ONOS Apps
75^^^^^^^^^
76
77The ONOS Apps need to be released in a different manner.
78
79There is a Jenkins job to release ONOS app: https://jenkins.opencord.org/job/onos-app-release.
80It requires to be triggered with specific parameters, as an example you can check the latest job in that pipeline.
81
821. Build with parameters: use the name of the repo (not of the app itself)
832. Wait for build to complete
843. Merge the patches on gerrit https://gerrit.opencord.org/q/owner:do-not-reply%2540opennetworking.org
Joey Armstrong56334fc2023-01-15 22:53:19 -050085
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
904. 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
94 - Login on sonatype (for username and password contact michelle@opennetworking.org)
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
1015. 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
1066. Iterate through apps:
107
108 - Modify pom.xml and dependencies.xml
109 - Update version string for all released dependencies.
110
Andrea Campanella4dfe9322022-05-10 12:40:10 +02001117. Start over with new app
112
113.. note::
114 Given their inter dependency the ONOS apps need to be released in order:
115
116 1. sadis
117 2. olt, aaa, dhcpl2relay, mcast, igmpproxy, maclearning
118 3. bng, PPPoE
119 4. kafka
120
121ONOS 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
136
137
138Creating the release
139--------------------
140
141Once the components have been tested and the release is considered ready there are 3 more elements that need to be
142tagged:
143
144- `VOLTHA Helm Charts <https://github.com/opencord/voltha-helm-charts>`_
145- `VOLTHA System Tests <https://github.com/opencord/voltha-system-tests>`_
146- `VOLTHA docs <https://github.com/opencord/voltha-docs>`_
147
148These 3 repos are the only ones that receive a X.Y.Z tag. Other repos that contain individual
149components have their own versioning/release cadence, driven by SemVer.
150
151Helm Charts
152^^^^^^^^^^^
153
154The official action of creating the voltha-X.Y release is releasing the voltha helm chart, and adapter charts
155with version:X.Y.Z (e.g. 2.10.0) specified in Chart.yaml within the voltha-helm-charts repo, and within the VERSION
156file in that repo.
157A branch named voltha-X.Y needs to be created on the voltha-helm-charts repo.
158The helm charts repo overall VERSION should also be incremented to the next minor version (X.Y+1-dev), so all X.Y.Z
159releases of the overall charts repo will happen on the voltha-X.Y branch.
160
161Voltha-system-tests
162^^^^^^^^^^^^^^^^^^^
163Accompanying tests for voltha-X.Y are created by creating a branch created named voltha-X.Y on the voltha-system-tests
164repo and creating a tag X.Y.Z on that branch.
165
166Documentation and Release Notes
167^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
168Release notes for the voltha-X.Y release are created and added to the voltha-docs repo. Please follow the template of
169past releases, an :doc:`example </voltha_releases/voltha_2.9>`
170
171Also, if needed a voltha-X.Y branch is created on docs repo. These release notes also contain all the
172versions of components that will be released, and may be updated during the final QA process.
173At release we create a tag X.Y.Z in the VERSION file.
174
175CI-Management
176^^^^^^^^^^^^^
177In the `Ci management <https://github.com/opencord/ci-management>`_ repository create the /voltha-x.y.z folder and copy the /master repos
178Testing CI jobs should be created that check out the voltha-X.Y branch of the voltha-system-tests repo, testing the
179charts as checked out with the voltha-X.Y tag of voltha-helm-charts.
180
181
182Release support and bug-fixing
183------------------------------
184
185What changes can be brought into the X.Y.Z branch?
186^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
187Has to be a bug or non-code fix.
188
189Add a Jira item with type Bug, tag against VOLTHA vX.Y
190Discuss on the Voltha mailing list, or in all-Voltha meeting, get consensus on whether should be brought to X.Y.z
191Documentation or other non-code updates are also acceptable
192
193What is a bug? Not a new feature!
194Anything that causes a functional regression test (Robot tests) to fail
195Severe issue (causes data loss or crash), or frequently occurring -> add to X.Y
196Issues that are merely annoying and don't cause data loss or a crash, or are very infrequently occurring -> may
197wait for next release
198
199WHen a bug is found please add to tests both on the released version and the master branch, if tests don't cover
200the bug. Add to Robot tests for integration-related issues, to Unit tests for code-level or functional issues.
201
202Update/Fixes to the released version
203^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
204This section shows how to create minor releases on the X.Y.Z branch when a bug fix is required.
205
206If a fix is needed to the helm charts:
207
208- Make the fix on the master branch of voltha-helm-charts (assuming that it is required in both places).
209- After the master tests pass, manually cherry-pick the fix to the voltha-X.Y branch (the Chart version would be
210 different, requiring the manual step).
211- Cherry-picked patchsets on that branch will be checked by the voltha-X.Y branch of tests.
212- When it passes, submitting the change will make a new X.Y.Z release
213- Update the documentation to reflect the chart changes, a description of the changes made, and increment the tag
214 on the docs from X.Y.Z to X.Y.Z+1, to reflect the patch change.
215- If all the charts are updated and working correctly, create a new charts point release by increasing the
216 X.Y.Z VERSION file in the voltha-helm-charts repo. The versions need to be updated in the voltha-docs repo,
217 which needs to be tagged as well, thus releasing it.
218
219If a fix is needed to the components/containers that are included by the helm charts:
220
221- Develop a fix to the issue on the master branch, get it approved after passing master tests.
Joey Armstrongd24a1122023-01-04 09:34:46 -0500222- Manually cherry-pick to the voltha-X.Y branch of the component (create one if needed)
Andrea Campanella4dfe9322022-05-10 12:40:10 +0200223- incrementing the patch version in the VERSION file,
224- test with the voltha-X.Y version of voltha-system-tests and helm charts.
225- Update helm charts and go through the helm chart update process above.
226- Update the voltha-docs with the right version of the component.
227
228If a fix is needed to the ONOS apps:
229
230- Create a branch here https://gerrit.opencord.org/plugins/gitiles/olt/+/refs/heads/olt-4.1
231- then `Git checkout -b <branch-name> opencord/<version>`
232- Then push a commit changing to `.1-SNAPSHOT` more (see e.g. https://gerrit.opencord.org/c/igmpproxy/+/19589)
233- Then push you changes (e.g. https://gerrit.opencord.org/c/igmpproxy/+/19590)
234- Then release as per the process above.
Joey Armstrong56334fc2023-01-15 22:53:19 -0500235
236See Also
237========
238- `VOLTHA Release Process <https://docs.voltha.org/master/overview/release_process.html?highlight=charts%20yaml>`_
239- `release_notes: Release Process <https://docs.voltha.org/master/release_notes/release_process.html>`_
240- `VOLTHA and ONOS Software Update Procedure <https://docs.voltha.org/master/operations/software-upgrade.html?highlight=set%20global%20image>`_
241- `Helm Chart Deployment <https://docs.voltha.org/master/voltha-helm-charts/README.html?highlight=voltctl>`_