docs/release-notes/upgrade-process.rst

   1 ==================================
   2 2023.09 Potassium Platform Upgrade
   3 ==================================
   4
   5 This document describes the steps to help users upgrade from Argon
   6 to Potassium platform. Refer to `Managed Snapshot Integrated (MSI)
   7 project <https://git.opendaylight.org/gerrit/q/topic:potassium-mri>`_
   8 upgrade patches for more information and hints for solutions to common
   9 problems not explicitly listed here.
  10
  11 .. contents:: Contents
  12
  13 Preparation
  14 -----------
  15
  16 JDK 17 Version
  17 ^^^^^^^^^^^^^^
  18 2023.09 Potassium, requires Java 17, both during compile-time and run-time.
  19 Make sure to install JDK 17 corresponding to at least ``openjdk-17.0.7``,
  20 and that the JAVA_HOME environment variable points to the JDK directory.
  21
  22 Version Bump
  23 ^^^^^^^^^^^^
  24 Before performing platform upgrade, do the following to bump the odlparent
  25 versions (for example, `bump-odl-version <https://github.com/skitt/odl-tools/blob/master/bump-odl-version>`_):
  26
  27 1. Update the odlparent version from 12.0.3 to 13.0.3. There should
  28    not be any reference to **org.opendaylight.odlparent**, except
  29    for 13.0.3. This includes custom feature.xml templates
  30    (``src/main/feature/feature.xml``), the version range should
  31    be "[13,14)" instead of "[11,12)", "[5.0.3,6)" or any other variation.
  32
  33  .. code-block:: shell
  34
  35   bump-odl-version odlparent 12.0.3 13.0.3
  36
  37 2. Update the direct yangtools version references from 10.0.4 to 11.0.0,
  38    There should not be any reference to **org.opendaylight.yangtools**,
  39    except for 11.0.0. This includes custom feature.xml templates
  40    (``src/main/feature/feature.xml``), the version range should
  41    be "[11,12)" instead of "[10,11)".
  42
  43  .. code-block:: shell
  44
  45   bump-odl-version yangtools 10.0.4 11.0.0
  46
  47 3. Update the MD-SAL version from 11.0.7 to 12.0.0. There should not be
  48    any reference to **org.opendaylight.mdsal**, except for 12.0.0.
  49
  50  .. code-block:: shell
  51
  52   bump-odl-version mdsal 11.0.7 12.0.0
  53
  54 4. Update the Controller version from 7.0.4 to 8.0.0. There should not be
  55    any reference to **org.opendaylight.controller**, except for 8.0.0.
  56
  57  .. code-block:: shell
  58
  59   bump-odl-version controller 7.0.4 8.0.0
  60
  61 5. Update the InfraUtils version from 5.0.3 to 6.0.1. There should not be
  62    any reference to **org.opendaylight.infrautils**, except for 6.0.1.
  63
  64  .. code-block:: shell
  65
  66   bump-odl-version infrautils 5.0.3 6.0.1
  67
  68 6. Update the AAA version from 0.17.7 to 0.18.0. There should not be
  69    any reference to **org.opendaylight.aaa**, except for 0.18.0.
  70
  71  .. code-block:: shell
  72
  73   bump-odl-version aaa 0.17.7 0.18.0
  74
  75 7. Update the NETCONF version from 5.0.4 to 6.0.0. There should not be
  76    any reference to **org.opendaylight.netconf**, except for 6.0.0.
  77
  78  .. code-block:: shell
  79
  80   bump-odl-version netconf 5.0.4 6.0.0
  81
  82 Install Dependent Projects
  83 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  84 Before performing platform upgrade, users must also install
  85 any dependent project. To locally install a dependent project,
  86 pull and install the respective
  87 `potassium-mri <https://git.opendaylight.org/gerrit/q/topic:potassium-mri>`_
  88 changes for any dependent project.
  89
  90 Perform the following steps to save time when locally installing
  91 any dependent project:
  92
  93 * For quick install:
  94
  95  .. code-block:: shell
  96
  97   mvn -Pq clean install
  98
  99 * If previously installed, go offline and/or use the
 100   no-snapshot-update option.
 101
 102  .. code-block:: shell
 103
 104   mvn -Pq -o -nsu clean install
 105
 106 Upgrade the ODL Parent
 107 ----------------------
 108 The following sub-section describes how to upgrade to
 109 the ODL Parent version 13. Refer to the `ODL Parent Release Notes
 110 <https://github.com/opendaylight/odlparent/blob/master/docs/NEWS.rst#version-1303>`_
 111 for more information.
 112
 113 Features
 114 ^^^^^^^^
 115 Any version range referencing version 11 of ODL Parent must be changed
 116 to “[13,14)” for ODL Parent 13.
 117
 118  .. code-block:: xml
 119
 120    <feature name="odl-infrautils-caches">
 121        <feature version="[13,14)">odl-guava</feature>
 122    </feature>
 123
 124 ODL Parent Impacts
 125 ------------------
 126
 127 Upstream declarations removed
 128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 129 The declaration of ``commons-lang`` dependency has been removed.
 130
 131 Default annotation declarations removed
 132 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 133 ``odlparent`` no longer declares ``spotbugs-annotations``, ``org.eclipse.jdt.annotation`` and ``modernizer-maven-annotations``
 134 as ``<scope>provided</scope>`` dependencies. Downstreams will need to introduce these annotations as appropriate.
 135
 136 YANG Tools Impacts
 137 ------------------
 138
 139 ``AugmentationIdentifer`` and ``AugmentationNode`` removed
 140 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 141 The class hierarchy of ``NormalizedNode`` has been updated to not contain augmented nodes in a separate ``AugmentationNode``,
 142 but rather keep them directly in the node being augmented. This results in a flatter NormalizedNode structure and makes constructing
 143 structures involving augmentations and reconciling them with ``EffectiveModelContext`` much more straightforward.
 144
 145 See `YANGTOOLS-568 <https://jira.opendaylight.org/browse/YANGTOOLS-568>`__ for details.
 146
 147 RFC7952 and RFC8528 support integrated into ``yang-data``
 148 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 149 The interfaces supporting RFC7952 YANG annotations have been integrated into ``yang-data-api`` and ``yang-data-util``
 150 artifacts. This rendered ``rfc7952-data-api`` and ``rfc7952-data-util`` artifacts empty and thus these have been removed.
 151 See `YANGTOOLS-1489 <https://jira.opendaylight.org/browse/YANGTOOLS-1489>`__ for details.
 152
 153 The interfaces supporting RFC8528 YANG schema mounts have been integrated into ``yang-data-api`` and ``yang-data-util``
 154 artifacts. This rendered ``rfc8528-data-api`` and ``rfc8528-data-util`` artifacts empty and thus these have been removed.
 155 See `YANGTOOLS-1172 <https://jira.opendaylight.org/browse/YANGTOOLS-1172>`__ for details.
 156
 157 As part of these changes, following API changes have also been done in order to ease using these interfaces:
 158 * ``NormalizedNodeStreamWriterExtension`` has been renamed to ``NormalizedNodeStreamWriter.Extension``
 159 * ``StreamWriterMetadataExtension`` has been renamed to ``NormalizedNodeStreamWriter.MetadataExtension``
 160 * ``StreamWriterMountPointExtension`` has been renamed to ``NormalizedNodeStreamWriter.MountPointExtension``
 161 * ``MountPointIdentifier`` has been removed with ``NormalizedMountPoint`` exposing its ``MountPointLabel`` directly
 162
 163 Finally, the result of ``NormalizedNodeStreamWriter`` is now a combined structure, ``NormalizationResult``, which combines
 164 a mandatory ``NormalizedNode`` data tree, an optional ``NormalizedMetadata`` and an optional ``NormalizedMountPoints`` tree.
 165 For the purposes of receiving this the result, ``NormalizedNodeResult`` has been replaced with ``NormalizationResultHolder``.
 166
 167 ``DataSchemaContextNode`` replaced with ``DataSchemaContext``
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 169 ``yang.data.util.DataSchemaContextNode`` has been completely revamped and renamed to ``DataSchemaContext``. It is now an interface
 170 implemented completely internally, with a proper interface hierarchy. Implementations of these interfaces are given out by
 171 ``DataSchemaContextTree``.  The resulting API is much easier to figure out and use, especially with proper documentation and naming
 172 not overlapping with other parts of YANG Tools.
 173 See `YANGTOOLS-1413 <https://jira.opendaylight.org/browse/YANGTOOLS-1413>`__ for details.
 174
 175 ``ExtensibleObject`` has been reworked
 176 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 177 This interface no longer exposes a ``ClassToInstanceMap``, but rather provides direct lookup and enumeration methods. Users need
 178 to be updated from performing
 179
 180   .. code-block:: java
 181
 182     ExtensibleObject obj;
 183     var extension = obj.getExtensions().getInstance(ExtensionType.class);
 184
 185 to instead doing
 186
 187   .. code-block:: java
 188
 189     ExtensibleObject obj;
 190     var extension = obj.extension(ExtensionType.class);
 191
 192 See `YANGTOOLS-1509 <https://jira.opendaylight.org/browse/YANGTOOLS-1509>`__ for details.
 193
 194 ``UsesNode.getRefines()`` exposes only descendant paths
 195 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 196 The return type was changed to return ``Set<Descendant>`` instead of ``Map<Descendant, SchemaNode>``. Users relying on accessing
 197 target nodes need to perform the resolution themselves.
 198 See `YANGTOOLS-1518 <https://jira.opendaylight.org/browse/YANGTOOLS-1518>`__ for details.
 199
 200 ``YangTextSchemaSources`` is a ``CharSource``
 201 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 202 ``yang.model.api.repo.YangTextSchemaSource`` now operates on a stream of characters, not bytes. All users which instantiate sources
 203 from byte streams must specify the character set used.
 204 See `YANGTOOLS-1508 <https://jira.opendaylight.org/browse/YANGTOOLS-1508>`__ for details.
 205
 206
 207 MD-SAL Impacts
 208 --------------
 209
 210 ``InstanceIdentifierBuilder`` renamed to ``InstanceIdentifier.Builder``
 211 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 212 A long-standing bug, where a ``KeyedInstanceIdentifier`` could not be safely returned from ``InstanceIdentifierBuilder`` was fixed.
 213 As part of this fix, ``InstanceIdentifierBuilder`` was renamed to be an inner class, ``InstanceIdentifier.Builder``. There is also
 214 a corresponding ``InstanceIdentifier.KeyedBuilder``. See `MDSAL-798 <https://jira.opendaylight.org/browse/MDSAL-798>`__ for details.
 215
 216 ``BindingReflections.getModuleInfo()`` has moved
 217 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 218 This reflection-based method was moved to ``BindingRuntimeHelpers`` class, as all its users already interact with
 219 ``mdsal-binding-runtime-spi``. See `MDSAL-803 <https://jira.opendaylight.org/browse/MDSAL-803>`__ for details.
 220
 221 Convenience model artifacts removed
 222 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 223 The aggregating multi-module RFCs have been removed. Users declaring a dependency on any of ``rfc6991``, ``rfc8294``, ``rfc8342``,
 224 ``rfc8345``, ``rfc8346``, ``rfc8348``, ``rfc8349``, ``rfc8519``, ``rfc8520``, ``rfc8542``, ``rfc8776`` or ``rfc8795`` need to now
 225 update these references to individual modules' artifacts.
 226 See `MDSAL-823 <https://jira.opendaylight.org/browse/MDSAL-823>`__ for details.
 227
 228 ``BindingMapping`` moved
 229 ^^^^^^^^^^^^^^^^^^^^^^^^
 230 ``binding.spec.naming.BindingMapping`` has been renamed and moved to ``yang.binding.contract.Naming``.
 231 See `MDSAL-804 <https://jira.opendaylight.org/browse/MDSAL-804>`__ for details.
 232
 233 ``IetfInetUtil.INSTANCE`` and ``IetfYangUtil.INSTANCE`` removed
 234 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 235 ``IetfInetUtil`` and ``IetfYangUtil`` have been refactored so they now expose static utility methods not encapsulated
 236 in an object instance. All references to ``INSTANCE`` need to be removed:
 237
 238   .. code-block:: java
 239
 240     byte[] bytes;
 241     IetfYangUtil.INSTANCE.macAddressFor(bytes);
 242
 243 becomes
 244
 245   .. code-block:: java
 246
 247     byte[] bytes;
 248     IetfYangUtil.macAddressFor(bytes);
 249
 250 See `MDSAL-804 <https://jira.opendaylight.org/browse/MDSAL-804>`__ for details.
 251
 252 Binding ``Identifiable`` and ``Identifier`` renamed
 253 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 254 ``yang.binding.Identifer`` has been renamed to ``yang.binding.Key`` and ``yang.binding.Identifiable`` has been renamed to
 255 ``yang.binding.KeyAware``. This change prevents confusion with ``yangtools.concepts`` interfaces with the same name.
 256 See `MDSAL-830 <https://jira.opendaylight.org/browse/MDSAL-830>`__ for details.
 257
 258
 259 Controller Impacts
 260 ------------------
 261 None.
 262