-=================================
-2022.09 Chlorine Platform Upgrade
-=================================
+==============================
+2023.03 Argon Platform Upgrade
+==============================
-This document describes the steps to help users upgrade from Sulfur
-to Chlorine planned platform. Refer to `Managed Snapshot Integrated (MSI)
-project <https://git.opendaylight.org/gerrit/q/topic:chlorine-mri>`_
+This document describes the steps to help users upgrade from Chlorine
+to Argon planned platform. Refer to `Managed Snapshot Integrated (MSI)
+project <https://git.opendaylight.org/gerrit/q/topic:argon-mri>`_
upgrade patches for more information and hints for solutions to common
problems not explicitly listed here.
JDK 17 Version
^^^^^^^^^^^^^^
-2022.09 Chlorine requires Java 17, both during compile-time and run-time.
-Make sure to install JDK 17 corresponding to at least ``openjdk-17.0.4``,
+2023.03 Argon requires Java 17, both during compile-time and run-time.
+Make sure to install JDK 17 corresponding to at least ``openjdk-17.0.5``,
and that the JAVA_HOME environment variable points to the JDK directory.
Version Bump
Before performing platform upgrade, do the following to bump the odlparent
versions (for example, `bump-odl-version <https://github.com/skitt/odl-tools/blob/master/bump-odl-version>`_):
-1. Update the odlparent version from 10.0.3 to 11.0.1. There should
+1. Update the odlparent version from 11.0.4 to 12.0.1. There should
not be any reference to **org.opendaylight.odlparent**, except
- for 11.0.1. This includes custom feature.xml templates
+ for 12.0.1. This includes custom feature.xml templates
(``src/main/feature/feature.xml``), the version range should
- be "[11,12)" instead of "[10,11)", "[5.0.3,6)" or any other variation.
+ be "[12,13)" instead of "[11,12)", "[5.0.3,6)" or any other variation.
.. code-block:: shell
- bump-odl-version odlparent 10.0.3 11.0.1
+ bump-odl-version odlparent 11.0.4 12.0.1
-2. Update the direct yangtools version references from 8.0.7 to 9.0.1,
+2. Update the direct yangtools version references from 9.0.6 to 10.0.2,
There should not be any reference to **org.opendaylight.yangtools**,
- except for 9.0.1. This includes custom feature.xml templates
+ except for 10.0.2. This includes custom feature.xml templates
(``src/main/feature/feature.xml``), the version range should
- be "[9,10)" instead of "[8,9)".
+ be "[10,11)" instead of "[9,10)".
.. code-block:: shell
- bump-odl-version yangtools 8.0.7 9.0.1
+ bump-odl-version yangtools 9.0.6 10.0.2
-3. Update the MD-SAL version from 9.0.5 to 10.0.2. There should not be
- any reference to **org.opendaylight.mdsal**, except for 10.0.2.
+3. Update the MD-SAL version from 10.0.6 to 11.0.4. There should not be
+ any reference to **org.opendaylight.mdsal**, except for 11.0.4.
.. code-block:: shell
- bump-odl-version mdsal 9.0.5 10.0.2
+ bump-odl-version mdsal 10.0.6 11.0.4
-4. Update the Controller version from 5.0.6 to 6.0.2. There should not be
- any reference to **org.opendaylight.controller**, except for 6.0.2.
+4. Update the Controller version from 6.0.7 to 7.0.2. There should not be
+ any reference to **org.opendaylight.controller**, except for 7.0.2.
.. code-block:: shell
- bump-odl-version controller 5.0.6 6.0.2
+ bump-odl-version controller 6.0.7 7.0.2
-5. Update the InfraUtils version from 3.0.2 to 4.0.1. There should not be
- any reference to **org.opendaylight.infrautils**, except for 4.0.1.
+5. Update the InfraUtils version from 4.0.4 to 5.0.1. There should not be
+ any reference to **org.opendaylight.infrautils**, except for 5.0.1.
.. code-block:: shell
- bump-odl-version infrautils 3.0.2 4.0.1
+ bump-odl-version infrautils 4.0.4 5.0.1
-6. Update the AAA version from 0.15.6 to 0.16.3. There should not be
- any reference to **org.opendaylight.aaa**, except for 0.16.3.
+6. Update the AAA version from 0.16.7 to 0.17.3. There should not be
+ any reference to **org.opendaylight.aaa**, except for 0.17.3.
.. code-block:: shell
- bump-odl-version aaa 0.15.6 0.16.3
+ bump-odl-version aaa 0.16.7 0.17.3
-7. Update the NETCONF version from 3.0.6 to 4.0.2. There should not be
- any reference to **org.opendaylight.netconf**, except for 4.0.2.
+7. Update the NETCONF version from 4.0.5 to 5.0.1. There should not be
+ any reference to **org.opendaylight.netconf**, except for 5.0.1.
.. code-block:: shell
- bump-odl-version netconf 3.0.6 4.0.2
+ bump-odl-version netconf 4.0.5 5.0.1
Install Dependent Projects
^^^^^^^^^^^^^^^^^^^^^^^^^^
Before performing platform upgrade, users must also install
any dependent project. To locally install a dependent project,
pull and install the respective
-`sulfur-mri <https://git.opendaylight.org/gerrit/q/topic:chlorine-mri>`_
+`argon-mri <https://git.opendaylight.org/gerrit/q/topic:argon-mri>`_
changes for any dependent project.
Perform the following steps to save time when locally installing
Upgrade the ODL Parent
----------------------
The following sub-section describes how to upgrade to
-the ODL Parent version 9. Refer to the `ODL Parent Release Notes
-<https://github.com/opendaylight/odlparent/blob/master/docs/NEWS.rst#version-1101>`_
+the ODL Parent version 12. Refer to the `ODL Parent Release Notes
+<https://github.com/opendaylight/odlparent/blob/master/docs/NEWS.rst#version-1201>`_
for more information.
Features
^^^^^^^^
-Any version range referencing version 10 of ODL Parent must be changed
-to “[11,12)” for ODL Parent 10.
+Any version range referencing version 11 of ODL Parent must be changed
+to “[12,13)” for ODL Parent 12.
.. code-block:: xml
<feature name="odl-infrautils-caches">
- <feature version="[11,12)">odl-guava</feature>
+ <feature version="[12,13)">odl-guava</feature>
</feature>
ODL Parent Impacts
Upstream declarations removed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A number of declarations of upstream projects, which are no longer used in OpenDaylight, have been removed. This
-includes ``Google Truth``, ``commons-codec``, ``commons-fileupload``, ``commons-net``, ``jsonassert``, ``jungg``
-and ``spring-osgi-mock``.
+The declaration of ``Enunciate``, both dependencies and maven plugin has been removed.
-Partial migration to Jakarta
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A number of Jakarta EE artifacts have been migrated from their legacy ``javax`` namespace to the new ``jakarta``
-namespace. This does not affect Java packages, only dependency declarations.
-
- .. list-table javax to Jakarta conversion
- :header-rows: 1
+JavaDoc HTML5 opt-out removed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Support for opting out from HTML5 JavaDocs has been removed. JavaDocs are always generated in HTML5.
- * - Old coordinate
- - New coordinate
- * - javax.activation/javax.activation-api
- - jakarta.activation/jakarta.activation-api
- * - javax.ws.rs/javax.ws.rs-api
- - jakarta.ws.rs/jakarta.ws.rs-api
+ANTLR updated to 4.11.x
+^^^^^^^^^^^^^^^^^^^^^^^
+The ANTLR declaration has been bumped to ``4.11.1``. While the version change would seem to indicate
+a backwards-update, this is not the case: all ANTLR grammars need to be recompiled with the new version.
+Any grammar from older ANTLR versions will not work.
YANG Tools Impacts
------------------
-SemVer-based YANG parser import resolution removed
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ability to recognize OpenConfig semantic versions in ``import`` statements and use them to resolve the import
-to a matching module has been removed.
-
-Multiple constructs are now ``sealed``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A number of interfaces and classes are now `sealed <https://openjdk.org/jeps/409>`__. This includes ``ItemOrder``,
-``AbstractQName``, ``ArgumentDefinition``, ``YangExpr``, ``ModelStatement``, ``YangInstanceIdentifier``, ``LeafSetNode``
-and ``MapNode``. This improves clarity of their design, making them easier to use and infer about, but also makes
-it impossible to use Mockito to mock them. Users may need to use real implementations instead of mocks.
+``EffectiveStatementNamespace`` removed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``EffectiveStatementNamespace`` and its specializations have been removed, as was the ability for
+``EffectiveStatement`` to address any namespace. Each namespace has been converted to a specific access method,
+for example ``DataTreeAwareEffectiveStatement.DataTreeNamespace`` is now exposed via
+``DataTreeAwareEffectiveStatement.dataTreeNodes()`` and ``DataTreeAwareEffectiveStatement.findDataTreeNode()``.
+See `YANGTOOLS-1459 <https://jira.opendaylight.org/browse/YANGTOOLS-1459>`__ for details.
-Decimal64 are required to match ``fraction-digits``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When a ``leaf`` or ``leaf-list`` item has ``type decimal64``, JSON and XML codecs will reject values which cannot
-be scaled to the matching ``fraction-digits``.
+``yang.model.api.SchemaPath`` removed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+SchemaPath is one of the oldest constructs with thoroughly inadequate and confusing semantics. Previous releases
+have gradually removed use of this construct. This release finally removes it. See
+`YANGTOOLS-1236 <https://jira.opendaylight.org/browse/YANGTOOLS-1236>`__ for details.
MD-SAL Impacts
--------------
-Improvements to generated ``toString()`` methods
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This release changes how generated ``toString()`` methods work in TypeObjects and with respect to ``byte[]`` properties.
-Property names now do not include a leading underscore. Byte array properties are now hex-encoded.
+``yang.binding.Enumeration`` renamed to ``yang.binding.EnumTypeObject``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In order to prevent potential confusion with ``java.util.Enumeration``, the base interfaces for classes generated
+for ``type enumeration`` YANG construct has been changed to ``EnumTypeObject``.
+
+Introduced ``yang.binding.BitsTypeObject``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Classes generated for ``type bits`` YANG construct have now implement a common interface ``BitsTypeObject``. This
+interface allows for unified access to the value as a ``boolean[]`` vector as well as valid bit names. See
+`MDSAL-743 <https://jira.opendaylight.org/browse/MDSAL-743>`__ for details.
-Mapping of ``identityref`` types changed
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Binding mapping of ``type identityref`` properties has changed. Given the following YANG snippet:
+Component bits are now mapped to primitive boolean
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Individual bits within a ``type bits`` value are now exposed as a primitive ``boolean`` rather than a ``Boolean``
+object. This provides for a better mapping, eliminating boxing as well as the problem of having a three-state
+(``true``, ``false`` and ``null``) components. See `MD-744 <https://jira.opendaylight.org/browse/MDSAL-744>`__
+for details.
- .. code-block:: yang
+Naming of ``action``-defined ``input`` and ``output`` statements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The naming of interfaces generated for ``input`` and ``output`` statements defined within an ``action`` statement
+has been changed to follow the same naming as those defined within an ``rpc`` statement. See
+`MDSAL-744 <https://jira.opendaylight.org/browse/MDSAL-744>`__ for details.
- identity foo;
+``DOMRpcService`` operates on ``ContainerNode``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+DOM interfaces related to RPC invocation, ``DOMRpcResult``, ``DOMRpcService`` and ``DOMRpcImplementation`` have
+all been updated to operate on ``ContainerNode`` rather than plain ``NormalizedNode``. This constitutes a change
+in API, but for most users this just ends up codifying their expectations. See
+`MDSAL-541 <https://jira.opendaylight.org/browse/MDSAL-541>`__ for details.
- leaf bar {
- type identityref {
- base foo;
- }
- }
-We see an interface ``Foo`` generated for the identity. This remains unchanged, but when setting the ``bar`` leaf,
-rather than using ``Foo.class``, users now need to specify ``Foo.VALUE``. This also affects use of ``type identityref``
-inside a ``type union``: each such use now gets its own property.
+Controller Impacts
+------------------
-Builders no longer generated for union types
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Due to historic reasons, code generated for ``type union`` statements included a Builder, which was generated in
-the ``src/main/java`` directory hierarchy. This Builder was hosting only a single ``getDefaultInstance()`` method,
-which needed to be hand-coded.
+Deprecated ``ask-based`` protocol
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Historic ``ask-based`` protocol has been superseded by ``tell-based`` protocol, which in turn is enabled by default.
+This release will produce a deprecation warning when ``ask-based`` protocol is enabled. See
+`CONTROLLER-2053 <https://jira.opendaylight.org/browse/CONTROLLER-2053>`__ for details.
-All of this mechanics has been removed and users are advised to remove these hand-crafted classes.
+Cross-datastore transactions are no longer supported
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The ability to modify ``OPERATIONAL`` and ``CONFIGURATION`` datastores in the same transaction has been removed. Any attempt
+to have a transaction access both datastores will result in an exception See
+`CONTROLLER-2055 <https://jira.opendaylight.org/browse/CONTROLLER-2055>`__ for details.
+Improved datastore access and persistence protocols
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Serialization formats for intra-node messages and ``sal-akka-raft`` journal entries have been improved, in some cases by more
+than 60%. See `CONTROLLER-2051 <https://jira.opendaylight.org/browse/CONTROLLER-2051>`__,
+`CONTROLLER-2056 <https://jira.opendaylight.org/browse/CONTROLLER-2056>`__ and
+`CONTROLLER-2058 <https://jira.opendaylight.org/browse/CONTROLLER-2058>`__ for details.
-Controller Impacts
-------------------
-No impacts in this release.
Code Review / docs.git / commitdiff