blob: 90ccc974078a83f23f947d085891fac4028cdf87 [file] [log] [blame]
Release Process
===============
This document describes the technical steps to create a new release of VOLTHA.
Creating the initial release
----------------------------
A release branch name is decided on, where all tagged releases will be created
in each repo. Historically this has been ``voltha`` followed by the Major and
Minor `Semver <https://semver.org/>`_ version, such as ``voltha-2.2``,
``voltha-2.3``, etc. The rest of this section will use the ``voltha-2.3``
release as an example:
A branch named ``voltha-2.3`` is created on the voltha-helm-charts repo. Release
candidates will be created of each chart for the ``2.3`` release. The action that
indicates the creation of the ``2.3`` release is to changing the `voltha
<https://gerrit.opencord.org/gitweb?p=voltha-helm-charts.git;a=tree;f=voltha>`_
helm chart, and adapter charts with version: ``2.3.0`` specified in ``Chart.yaml``
within the `voltha-helm-charts
<https://gerrit.opencord.org/gitweb?p=voltha-helm-charts.git;a=summary>`_ repo.
Accompanying tests for 2.3 are created by creating a branch created named
``voltha-2.3`` on the `voltha-system-tests
<https://gerrit.opencord.org/gitweb?p=voltha-system-tests.git;a=summary>`_
repo. At release we create a tag ``2.3.0`` on that branch.
These two repos are the only ones that receive a ``2.3.0`` tag. Other repos that
contain individual components have their own versioning/release cadence, driven
by SemVer.
For all other repos that create components that go into the release, tags will
be created and ``voltha-2.3`` branches are created starting from the tag.
To allow for future patches to go into the repo in a way that does not conflict
with the patch version, each component repo's ``VERSION`` file should have it's
Minor version increased. (ex: ``1.1.x`` to ``1.2.0-dev``, so future ``1.1.x+1``
component release can easily be created).
Testing CI jobs will be created that check out the voltha-2.3 branch of the
`voltha-system-tests
<https://gerrit.opencord.org/gitweb?p=voltha-system-tests.git;a=summary>`_
repo, testing the charts as checked out with the ``voltha-2.3`` branch of
``voltha-helm-charts``. Patches on the ``voltha-2.3`` branch of components
that build containers will need to be changed to rebuild those containers and
test with the ``voltha-2.3`` branch of helm charts.
Creating point releases on a stable branch
------------------------------------------
If a fix is only needed to the helm charts:
- Make the fix on the master branch of voltha-helm-charts (assuming that it is
required in both places).
- After the master tests pass, manually cherry-pick the fix to the voltha-2.3
branch (the Chart.yaml version would be different, requiring the manual
step).
- Cherry-picked patchsets on that branch will be checked by the voltha-2.3
branch of tests.
- When it passes, submitting the change will make a new 2.3.x release
If a fix is needed to the components/containers that are included by the helm
charts:
- Develop a fix to the issue on the master branch, get it approved after
passing master tests.
- Manually cherry-pick to the voltha-2.3 branch of the component, incrementing
the patch version, and test with the voltha-2.3 version of
voltha-system-tests and helm charts.
- Update helm charts and go through the helm chart update process above.
What changes can be brought into a stable branch?
-------------------------------------------------
For a change to be suitable for a stable branch, it has to be either a:
- Bug
- Non-code fix (documentation, build process)
- Security or compatibility updates (problem found in a dependency, upstream
software EOL, etc.)
Process to create a change on a stable branch
- Add a Jira item, with the ``Affects Version: ``VOLTHA vX.X`` set
- Discuss and get consensus on the issue via the Voltha mailing list, in the
all-Voltha meeting, or on Slack about whether this fix should be brought to a
stable branch
- Create a fix, and go through the integration process to create a new point
release.
What is a bug?
""""""""""""""
- Anything that causes a functional regression test (Robot tests) to fail
- Not a new feature!
- Severe issue (causes data loss or crash), or frequently occurring are
generally more likely to be accepted.
- Issues that are merely annoying and don't cause data loss or a crash, or
happen very infrequently or can't be reproduced may not be.
As a best practice, please add tests when bugs are found, if tests don't
currently cover the particular bug. Examples:
- Robot tests for integration-related issues
- Unit tests for code-level issues
API Deprecation policy
----------------------
VOLTHA has in place a 2 release deprecation policy. Starting from ``voltha-2.9`` the APIs that are marked as deprecated
are automatically removed after 2 releases.
As an example an API marked as deprecated in ``voltha-2.9`` will be removed after the ``voltha-2.10`` release
and will not be present anymore in ``voltha-2.11``.
The removal process is intended to happen automatically, meaning no further notice of removal needs to be sent out.
The deprecated objects and APIs are marked in the `voltha-protos <https://github.com/opencord/voltha-protos>`_ using the
``deprecated`` construct from protobuf, as per `specification <https://developers.google.com/protocol-buffers/docs/proto3>`_.
An example is ``int32 old_field = 6 [deprecated = true];``
Repos (lazily) branched for each release
----------------------------------------
Charts
""""""
- voltha-helm-charts
Testing
"""""""
- voltha-system-tests
- pod-configs
Tools
"""""
- bbsim (also creates containers)
- voltctl
ONOS Apps
"""""""""
- aaa
- dhcpl2relay
- igmpproxy
- kafka
- mcast
- olt
- sadis
- mac-learning
Libraries
"""""""""
- voltha-lib-go
- voltha-protos
Components (which build containers)
"""""""""""""""""""""""""""""""""""
- ofagent-go
- voltha-go (rw_core)
- voltha-openolt-adapter
- voltha-openonu-adapter-go
- voltha-onos (includes ONOS Apps)