blob: cbdfff5426be48abef5b1782571839caaec31625 [file] [log] [blame]
Joey Armstrong2a687952023-02-01 13:10:12 -05001.. |voltha-latest| replace:: voltha_2.11
2
Zack Williams16042b62020-03-29 22:03:16 -07003Release Process
4===============
5
6This document describes the technical steps to create a new release of VOLTHA.
7
8Creating the initial release
9----------------------------
10
11A release branch name is decided on, where all tagged releases will be created
12in each repo. Historically this has been ``voltha`` followed by the Major and
Joey Armstrong2a687952023-02-01 13:10:12 -050013Minor `Semver <https://semver.org/>`_ version, such as ``voltha-2.3``,
14etc. The rest of this section will use the ``voltha-2.3`` release as an
15example:
Zack Williams16042b62020-03-29 22:03:16 -070016
Joey Armstronged6cedd2022-08-31 12:39:33 -040017A branch named ``voltha-2.3`` is created on the voltha-helm-charts repo.
18Release candidates will be created of each chart for the ``2.3`` release.
19The action that indicates the creation of the ``2.3`` release is to changing
20the `voltha
Zack Williams16042b62020-03-29 22:03:16 -070021<https://gerrit.opencord.org/gitweb?p=voltha-helm-charts.git;a=tree;f=voltha>`_
Joey Armstronged6cedd2022-08-31 12:39:33 -040022helm chart, and adapter charts with version: ``2.3.0`` specified in
23``Chart.yaml`` within the `voltha-helm-charts
Zack Williams16042b62020-03-29 22:03:16 -070024<https://gerrit.opencord.org/gitweb?p=voltha-helm-charts.git;a=summary>`_ repo.
25
26Accompanying tests for 2.3 are created by creating a branch created named
27``voltha-2.3`` on the `voltha-system-tests
28<https://gerrit.opencord.org/gitweb?p=voltha-system-tests.git;a=summary>`_
29repo. At release we create a tag ``2.3.0`` on that branch.
30
Joey Armstronged6cedd2022-08-31 12:39:33 -040031These two repos are the only ones receiving a ``2.3.0`` tag. Other repos that
Zack Williams16042b62020-03-29 22:03:16 -070032contain individual components have their own versioning/release cadence, driven
33by SemVer.
34
35For all other repos that create components that go into the release, tags will
36be created and ``voltha-2.3`` branches are created starting from the tag.
37
38To allow for future patches to go into the repo in a way that does not conflict
39with the patch version, each component repo's ``VERSION`` file should have it's
40Minor version increased. (ex: ``1.1.x`` to ``1.2.0-dev``, so future ``1.1.x+1``
41component release can easily be created).
42
43Testing CI jobs will be created that check out the voltha-2.3 branch of the
44`voltha-system-tests
45<https://gerrit.opencord.org/gitweb?p=voltha-system-tests.git;a=summary>`_
46repo, testing the charts as checked out with the ``voltha-2.3`` branch of
47``voltha-helm-charts``. Patches on the ``voltha-2.3`` branch of components
48that build containers will need to be changed to rebuild those containers and
49test with the ``voltha-2.3`` branch of helm charts.
50
51Creating point releases on a stable branch
52------------------------------------------
53
54If a fix is only needed to the helm charts:
55
56- Make the fix on the master branch of voltha-helm-charts (assuming that it is
57 required in both places).
58
59- After the master tests pass, manually cherry-pick the fix to the voltha-2.3
60 branch (the Chart.yaml version would be different, requiring the manual
61 step).
62
63- Cherry-picked patchsets on that branch will be checked by the voltha-2.3
64 branch of tests.
65
66- When it passes, submitting the change will make a new 2.3.x release
67
68If a fix is needed to the components/containers that are included by the helm
69charts:
70
71- Develop a fix to the issue on the master branch, get it approved after
72 passing master tests.
73
74- Manually cherry-pick to the voltha-2.3 branch of the component, incrementing
75 the patch version, and test with the voltha-2.3 version of
76 voltha-system-tests and helm charts.
77
78- Update helm charts and go through the helm chart update process above.
79
80
81What changes can be brought into a stable branch?
82-------------------------------------------------
83
84For a change to be suitable for a stable branch, it has to be either a:
85
86- Bug
87- Non-code fix (documentation, build process)
88- Security or compatibility updates (problem found in a dependency, upstream
89 software EOL, etc.)
90
91Process to create a change on a stable branch
92
Joey Armstronged6cedd2022-08-31 12:39:33 -040093- Create a jira ticket for the problem and document the ``Affects Version/s:``
94 - field with affected version(s) ``VOLTHA vX.X``.
Zack Williams16042b62020-03-29 22:03:16 -070095- Discuss and get consensus on the issue via the Voltha mailing list, in the
96 all-Voltha meeting, or on Slack about whether this fix should be brought to a
97 stable branch
98- Create a fix, and go through the integration process to create a new point
99 release.
100
101What is a bug?
102""""""""""""""
103
104- Anything that causes a functional regression test (Robot tests) to fail
105- Not a new feature!
106- Severe issue (causes data loss or crash), or frequently occurring are
107 generally more likely to be accepted.
108- Issues that are merely annoying and don't cause data loss or a crash, or
109 happen very infrequently or can't be reproduced may not be.
110
111As a best practice, please add tests when bugs are found, if tests don't
112currently cover the particular bug. Examples:
113
114- Robot tests for integration-related issues
115- Unit tests for code-level issues
116
Andrea Campanella542291b2021-10-27 16:18:46 +0200117API Deprecation policy
118----------------------
Joey Armstronged6cedd2022-08-31 12:39:33 -0400119VOLTHA supports 2 release deprecation policy. Starting from ``voltha-2.9``
120the APIs that are marked as deprecated are automatically removed.
121For example an API marked as deprecated in ``voltha-2.9`` will be removed after
122the ``voltha-2.10`` release and will not be present anymore in ``voltha-2.11``.
Andrea Campanella542291b2021-10-27 16:18:46 +0200123
124The removal process is intended to happen automatically, meaning no further notice of removal needs to be sent out.
125The deprecated objects and APIs are marked in the `voltha-protos <https://github.com/opencord/voltha-protos>`_ using the
126``deprecated`` construct from protobuf, as per `specification <https://developers.google.com/protocol-buffers/docs/proto3>`_.
127An example is ``int32 old_field = 6 [deprecated = true];``
128
129
130Repos (lazily) branched for each release
131----------------------------------------
Zack Williams16042b62020-03-29 22:03:16 -0700132
133Charts
134""""""
135
136- voltha-helm-charts
137
138Testing
139"""""""
140
141- voltha-system-tests
Andrea Campanella542291b2021-10-27 16:18:46 +0200142- pod-configs
Zack Williams16042b62020-03-29 22:03:16 -0700143
144Tools
145"""""
146
147- bbsim (also creates containers)
148- voltctl
149
150ONOS Apps
151"""""""""
152
153- aaa
154- dhcpl2relay
Andrea Campanella542291b2021-10-27 16:18:46 +0200155- igmpproxy
Zack Williams16042b62020-03-29 22:03:16 -0700156- kafka
157- mcast
158- olt
159- sadis
Andrea Campanella542291b2021-10-27 16:18:46 +0200160- mac-learning
Zack Williams16042b62020-03-29 22:03:16 -0700161
162Libraries
163"""""""""
164
Zack Williams16042b62020-03-29 22:03:16 -0700165- voltha-lib-go
166- voltha-protos
167
168Components (which build containers)
169"""""""""""""""""""""""""""""""""""
170- ofagent-go
171- voltha-go (rw_core)
172- voltha-openolt-adapter
Andrea Campanellac18d1182021-09-10 12:01:38 +0200173- voltha-openonu-adapter-go
Zack Williams16042b62020-03-29 22:03:16 -0700174- voltha-onos (includes ONOS Apps)