Update docs for 2023.09 Potassium

Upgrade release notes and upgrade guide to reflect 2023.09 changes.

Change-Id: I993fec80ac5ff87f61664b380115dd36e198594f
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/docs/release-notes/projects/aaa.rst b/docs/release-notes/projects/aaa.rst
index e03911f43b171ff645ea016da39fb221726a3db4..583ef386254042a71c2fb6cfe4f772f01baefe50 100644 (file)
--- a/docs/release-notes/projects/aaa.rst
+++ b/docs/release-notes/projects/aaa.rst
@@ -28,7 +28,7 @@ The following table lists the issues resolved in this release.
 
 .. jira_fixed_issues::
    :project: AAA
 
 .. jira_fixed_issues::
    :project: AAA

-   :versions: 0.17.0-0.17.7
+   :versions: 0.18.0-0.18.0

 
 Known Issues
 ============
 
 Known Issues
 ============


@@ -36,4 +36,4 @@ The following table lists the known issues that exist in this release.
 
 .. jira_known_issues::
    :project: AAA
 
 .. jira_known_issues::
    :project: AAA

-   :versions: 0.17.0-0.17.7
+   :versions: 0.18.0-0.18.0

diff --git a/docs/release-notes/projects/bgpcep.rst b/docs/release-notes/projects/bgpcep.rst
index 16cc1be997bd89a7a4939e3baef8f4790ebd58a0..b94e93c7e6e7acd43f418289d9bb8169fecf9f55 100644 (file)
--- a/docs/release-notes/projects/bgpcep.rst
+++ b/docs/release-notes/projects/bgpcep.rst
@@ -41,11 +41,7 @@ the following components:
 
 Behavior/Feature Changes
 ========================
 
 Behavior/Feature Changes
 ========================

-``pcep-topology-provider`` now allows PCEP capabilities, TLS configuration as well as PCEP
-timer proposals to be configured on a per-topology basis rather than being global settings.
-
-Rarely-used configuration knobs for PCEP ``auto-bandwidth`` and ``segment-routing`` extensions
-have been migrated from the datastore to OSGi Configuration Admin properties.
+No changes.

 
 
 New Features
 
 
 New Features


@@ -62,7 +58,7 @@ The following table lists the issues resolved in this release.
 
 .. jira_fixed_issues::
    :project: BGPCEP
 
 .. jira_fixed_issues::
    :project: BGPCEP

-   :versions: 0.19.0-0.19.3
+   :versions: 0.20.0-0.20.0

 
 Known Issues
 ============
 
 Known Issues
 ============


@@ -70,4 +66,4 @@ The following table lists the known issues that exist in this release.
 
 .. jira_known_issues::
    :project: BGPCEP
 
 .. jira_known_issues::
    :project: BGPCEP

-   :versions: 0.19.0-0.19.3
+   :versions: 0.20.0-0.20.0

diff --git a/docs/release-notes/projects/controller.rst b/docs/release-notes/projects/controller.rst
index a6be67b4ae387cf7ff39516bc81dada6316b2b2c..4517f06d35c88126cdd1ec27abc0a7ba0fa0daed 100644 (file)
--- a/docs/release-notes/projects/controller.rst
+++ b/docs/release-notes/projects/controller.rst
@@ -11,7 +11,13 @@ It does not have user-facing features.
 
 Behavior/Feature Changes
 ========================
 
 Behavior/Feature Changes
 ========================

-No changes.
+This release does not support running mixed-versions clusters. This precludes in-place on-line upgrades,
+as 2023.09 Potassium nodes cannot interchange data with nodes running previous versions in a compatible
+manner. In order to perform the upgrade to 2023.09 Potassium, upgrade one node to this version, then reduce
+the cluster to that single node, then upgrade all the other nodes and then re-grow the cluster to include
+those nodes.
+
+This upgrade is not directly reversible, once upgraded, a node cannot be downgraded to below 2023.09 Potassium.

 
 New Features
 ============
 
 New Features
 ============


@@ -29,7 +35,7 @@ The following table lists the issues resolved in this release.
 
 .. jira_fixed_issues::
    :project: CONTROLLER
 
 .. jira_fixed_issues::
    :project: CONTROLLER

-   :versions: 7.0.0-7.0.4
+   :versions: 8.0.0-8.0.0

 
 Known Issues
 ============
 
 Known Issues
 ============


@@ -37,4 +43,4 @@ The following table lists the known issues that exist in this release.
 
 .. jira_known_issues::
    :project: CONTROLLER
 
 .. jira_known_issues::
    :project: CONTROLLER

-   :versions: 7.0.0-7.0.4
+   :versions: 8.0.0-8.0.0

diff --git a/docs/release-notes/projects/infrautils.rst b/docs/release-notes/projects/infrautils.rst
index b64acbd30b25903efbc9ba62b0c7f24281fcae8c..7ad10f4b9ef625d922b1c859fa0030f1ad7d4e56 100644 (file)
--- a/docs/release-notes/projects/infrautils.rst
+++ b/docs/release-notes/projects/infrautils.rst
@@ -32,7 +32,7 @@ The following table lists the issues resolved in this release.
 
 .. jira_fixed_issues::
    :project: INFRAUTILS
 
 .. jira_fixed_issues::
    :project: INFRAUTILS

-   :versions: 5.0.0-5.0.3
+   :versions: 6.0.0-6.0.1

 
 Known Issues
 ============
 
 Known Issues
 ============


@@ -40,4 +40,4 @@ The following table lists the known issues that exist in this release.
 
 .. jira_known_issues::
    :project: INFRAUTILS
 
 .. jira_known_issues::
    :project: INFRAUTILS

-   :versions: 5.0.0-5.0.3
+   :versions: 6.0.0-6.0.1

diff --git a/docs/release-notes/projects/mdsal.rst b/docs/release-notes/projects/mdsal.rst
index 588f7ed2016603eb6770f270db0706474011d6d0..518eb242a90ca7718b7f15093370d017e7c1acde 100644 (file)
--- a/docs/release-notes/projects/mdsal.rst
+++ b/docs/release-notes/projects/mdsal.rst
@@ -45,7 +45,7 @@ The following table lists the issues resolved in this release.
 
 .. jira_fixed_issues::
    :project: MDSAL
 
 .. jira_fixed_issues::
    :project: MDSAL

-   :versions: 11.0.0-11.0.7
+   :versions: 12.0.0-12.0.0

 
 Known Issues
 ============
 
 Known Issues
 ============


@@ -53,4 +53,4 @@ The following table lists the known issues that exist in this release.
 
 .. jira_known_issues::
    :project: MDSAL
 
 .. jira_known_issues::
    :project: MDSAL

-   :versions: 11.0.0-11.0.7
+   :versions: 12.0.0-12.0.0

diff --git a/docs/release-notes/projects/netconf.rst b/docs/release-notes/projects/netconf.rst
index 702e39e415af6351ed121d31d58ea9740155b283..1790188587cb0309a8d7276a5d48c6edd47cb7f8 100644 (file)
--- a/docs/release-notes/projects/netconf.rst
+++ b/docs/release-notes/projects/netconf.rst
@@ -34,7 +34,7 @@ The following table lists the issues resolved in this release.
 
 .. jira_fixed_issues::
    :project: NETCONF
 
 .. jira_fixed_issues::
    :project: NETCONF

-   :versions: 5.0.0-5.0.4
+   :versions: 6.0.0-6.0.0

 
 Known Issues
 ============
 
 Known Issues
 ============


@@ -42,4 +42,4 @@ The following table lists the known issues that exist in this release.
 
 .. jira_known_issues::
    :project: NETCONF
 
 .. jira_known_issues::
    :project: NETCONF

-   :versions: 5.0.0-5.0.4
+   :versions: 6.0.0-6.0.0

diff --git a/docs/release-notes/projects/yangtools.rst b/docs/release-notes/projects/yangtools.rst
index 3f532c862d6b72f23d497a052c08b4ba2f04542f..2476d747993b0fd9d82a72d7ef13bb7cdf9f4631 100644 (file)
--- a/docs/release-notes/projects/yangtools.rst
+++ b/docs/release-notes/projects/yangtools.rst
@@ -8,19 +8,22 @@ YANG Tools provides a set of libraries to deal with YANG models and data modeled
 
 Behavior/Feature Changes
 ========================
 
 Behavior/Feature Changes
 ========================

-XML and JSON parsers now ensure ``type decimal64`` values are validated to be within the range
-implied by their ``fraction-digits`` statements.
+The mapping of YANG augmentations in ``yang-data-api`` has changed. Where previously these have
+been supported by ``AugmetationNode`` and addressable via ``AugmentationIdentifier``, any augmented
+nodes are now direct children of their ``data tree`` parent nodes.
+
+``YangTextSchemaSource`` is now a ``CharSource`` rather than a ``ByteSource``. This eliminates ambiguity
+and assumptions made on the text encoding character set, pushing the responsibility down to users
+introducing schema sources into the system.

 
 New Features
 ============
 
 New Features
 ============

-No new features.
+``yang-maven-plugin`` now executes during incremental builds and does its best to not overwrite
+unchanged outputs.

 
 Removed Features
 ================
 
 Removed Features
 ================

-Code generation plugin APIs for ``yang-maven-plugin`` contained in the ``yang-maven-plugin-spi``
-artifact were removed.
-
-The ``SchemaPath`` class has been removed.
+``AugmentationNode`` and ``AugmentationIdentifer`` constructs have been removed.

 
 Deprecated Features
 ===================
 
 Deprecated Features
 ===================


@@ -32,7 +35,7 @@ The following table lists the issues resolved in this release.
 
 .. jira_fixed_issues::
    :project: YANGTOOLS
 
 .. jira_fixed_issues::
    :project: YANGTOOLS

-   :versions: 10.0.0-10.0.4
+   :versions: 11.0.0-11.0.0

 
 Known Issues
 ============
 
 Known Issues
 ============


@@ -40,4 +43,4 @@ The following table lists the known issues that exist in this release.
 
 .. jira_known_issues::
    :project: YANGTOOLS
 
 .. jira_known_issues::
    :project: YANGTOOLS

-   :versions: 10.0.0-10.0.4
+   :versions: 11.0.0-11.0.0

diff --git a/docs/release-notes/upgrade-process.rst b/docs/release-notes/upgrade-process.rst
index 30befdd141c76eaccf6f6adf5b57ee20ccf49d4d..ed3998e8f9dcdfe364887ea23b293b9b58ecb1f5 100644 (file)
--- a/docs/release-notes/upgrade-process.rst
+++ b/docs/release-notes/upgrade-process.rst
@@ -1,10 +1,10 @@
-==============================
-2023.03 Argon Platform Upgrade
-==============================
+==================================
+2023.09 Potassium Platform Upgrade
+==================================

 
 

-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>`_
+This document describes the steps to help users upgrade from Argon
+to Potassium platform. Refer to `Managed Snapshot Integrated (MSI)
+project <https://git.opendaylight.org/gerrit/q/topic:potassium-mri>`_

 upgrade patches for more information and hints for solutions to common
 problems not explicitly listed here.
 
 upgrade patches for more information and hints for solutions to common
 problems not explicitly listed here.
 


@@ -15,8 +15,8 @@ Preparation
 
 JDK 17 Version
 ^^^^^^^^^^^^^^
 
 JDK 17 Version
 ^^^^^^^^^^^^^^

-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``,
+2023.09 Potassium, requires Java 17, both during compile-time and run-time.
+Make sure to install JDK 17 corresponding to at least ``openjdk-17.0.7``,

 and that the JAVA_HOME environment variable points to the JDK directory.
 
 Version Bump
 and that the JAVA_HOME environment variable points to the JDK directory.
 
 Version Bump


@@ -24,67 +24,67 @@ 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>`_):
 
 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 11.0.4 to 12.0.3. There should
+1. Update the odlparent version from 12.0.3 to 13.0.3. There should

    not be any reference to **org.opendaylight.odlparent**, except
    not be any reference to **org.opendaylight.odlparent**, except

-   for 12.0.3. This includes custom feature.xml templates
+   for 13.0.3. This includes custom feature.xml templates

    (``src/main/feature/feature.xml``), the version range should
    (``src/main/feature/feature.xml``), the version range should

-   be "[12,13)" instead of "[11,12)", "[5.0.3,6)" or any other variation.
+   be "[13,14)" instead of "[11,12)", "[5.0.3,6)" or any other variation.

 
  .. code-block:: shell
 
 
  .. code-block:: shell
 

-  bump-odl-version odlparent 11.0.4 12.0.3
+  bump-odl-version odlparent 12.0.3 13.0.3

 
 

-2. Update the direct yangtools version references from 9.0.6 to 10.0.4,
+2. Update the direct yangtools version references from 10.0.4 to 11.0.0,

    There should not be any reference to **org.opendaylight.yangtools**,
    There should not be any reference to **org.opendaylight.yangtools**,

-   except for 10.0.4. This includes custom feature.xml templates
+   except for 11.0.0. This includes custom feature.xml templates

    (``src/main/feature/feature.xml``), the version range should
    (``src/main/feature/feature.xml``), the version range should

-   be "[10,11)" instead of "[9,10)".
+   be "[11,12)" instead of "[10,11)".

 
  .. code-block:: shell
 
 
  .. code-block:: shell
 

-  bump-odl-version yangtools 9.0.6 10.0.4
+  bump-odl-version yangtools 10.0.4 11.0.0

 
 

-3. Update the MD-SAL version from 10.0.6 to 11.0.7. There should not be
-   any reference to **org.opendaylight.mdsal**, except for 11.0.7.
+3. Update the MD-SAL version from 11.0.7 to 12.0.0. There should not be
+   any reference to **org.opendaylight.mdsal**, except for 12.0.0.

 
  .. code-block:: shell
 
 
  .. code-block:: shell
 

-  bump-odl-version mdsal 10.0.6 11.0.7
+  bump-odl-version mdsal 11.0.7 12.0.0

 
 

-4. Update the Controller version from 6.0.7 to 7.0.4. There should not be
-   any reference to **org.opendaylight.controller**, except for 7.0.4.
+4. Update the Controller version from 7.0.4 to 8.0.0. There should not be
+   any reference to **org.opendaylight.controller**, except for 8.0.0.

 
  .. code-block:: shell
 
 
  .. code-block:: shell
 

-  bump-odl-version controller 6.0.7 7.0.2
+  bump-odl-version controller 7.0.4 8.0.0

 
 

-5. Update the InfraUtils version from 4.0.4 to 5.0.3. There should not be
-   any reference to **org.opendaylight.infrautils**, except for 5.0.3.
+5. Update the InfraUtils version from 5.0.3 to 6.0.1. There should not be
+   any reference to **org.opendaylight.infrautils**, except for 6.0.1.

 
  .. code-block:: shell
 
 
  .. code-block:: shell
 

-  bump-odl-version infrautils 4.0.4 5.0.1
+  bump-odl-version infrautils 5.0.3 6.0.1

 
 

-6. Update the AAA version from 0.16.7 to 0.17.7. There should not be
-   any reference to **org.opendaylight.aaa**, except for 0.17.7.
+6. Update the AAA version from 0.17.7 to 0.18.0. There should not be
+   any reference to **org.opendaylight.aaa**, except for 0.18.0.

 
  .. code-block:: shell
 
 
  .. code-block:: shell
 

-  bump-odl-version aaa 0.16.7 0.17.3
+  bump-odl-version aaa 0.17.7 0.18.0

 
 

-7. Update the NETCONF version from 4.0.5 to 5.0.4. There should not be
-   any reference to **org.opendaylight.netconf**, except for 5.0.4.
+7. Update the NETCONF version from 5.0.4 to 6.0.0. There should not be
+   any reference to **org.opendaylight.netconf**, except for 6.0.0.

 
  .. code-block:: shell
 
 
  .. code-block:: shell
 

-  bump-odl-version netconf 4.0.5 5.0.1
+  bump-odl-version netconf 5.0.4 6.0.0

 
 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
 
 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

-`argon-mri <https://git.opendaylight.org/gerrit/q/topic:argon-mri>`_
+`potassium-mri <https://git.opendaylight.org/gerrit/q/topic:potassium-mri>`_

 changes for any dependent project.
 
 Perform the following steps to save time when locally installing
 changes for any dependent project.
 
 Perform the following steps to save time when locally installing


@@ -106,19 +106,19 @@ any dependent project:
 Upgrade the ODL Parent
 ----------------------
 The following sub-section describes how to upgrade to
 Upgrade the ODL Parent
 ----------------------
 The following sub-section describes how to upgrade to

-the ODL Parent version 12. Refer to the `ODL Parent Release Notes
-<https://github.com/opendaylight/odlparent/blob/master/docs/NEWS.rst#version-1201>`_
+the ODL Parent version 13. Refer to the `ODL Parent Release Notes
+<https://github.com/opendaylight/odlparent/blob/master/docs/NEWS.rst#version-1303>`_

 for more information.
 
 Features
 ^^^^^^^^
 Any version range referencing version 11 of ODL Parent must be changed
 for more information.
 
 Features
 ^^^^^^^^
 Any version range referencing version 11 of ODL Parent must be changed

-to “[12,13)” for ODL Parent 12.
+to “[13,14)” for ODL Parent 13.

 
  .. code-block:: xml
 
    <feature name="odl-infrautils-caches">
 
  .. code-block:: xml
 
    <feature name="odl-infrautils-caches">

-       <feature version="[12,13)">odl-guava</feature>
+       <feature version="[13,14)">odl-guava</feature>

    </feature>
 
 ODL Parent Impacts
    </feature>
 
 ODL Parent Impacts


@@ -126,90 +126,137 @@ ODL Parent Impacts
 
 Upstream declarations removed
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Upstream declarations removed
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-The declaration of ``Enunciate``, both dependencies and maven plugin has been removed.
+The declaration of ``commons-lang`` dependency has been removed.

 
 

-JavaDoc HTML5 opt-out removed
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Support for opting out from HTML5 JavaDocs has been removed. JavaDocs are always generated in HTML5.
-
-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.
+Default annotation declarations removed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``odlparent`` no longer declares ``spotbugs-annotations``, ``org.eclipse.jdt.annotation`` and ``modernizer-maven-annotations``
+as ``<scope>provided</scope>`` dependencies. Downstreams will need to introduce these annotations as appropriate.

 
 YANG Tools Impacts
 ------------------
 
 
 YANG Tools Impacts
 ------------------
 

-``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.
+``AugmentationIdentifer`` and ``AugmentationNode`` removed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The class hierarchy of ``NormalizedNode`` has been updated to not contain augmented nodes in a separate ``AugmentationNode``,
+but rather keep them directly in the node being augmented. This results in a flatter NormalizedNode structure and makes constructing
+structures involving augmentations and reconciling them with ``EffectiveModelContext`` much more straightforward.
+
+See `YANGTOOLS-568 <https://jira.opendaylight.org/browse/YANGTOOLS-568>`__ for details.
+
+RFC7952 and RFC8528 support integrated into ``yang-data``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The interfaces supporting RFC7952 YANG annotations have been integrated into ``yang-data-api`` and ``yang-data-util``
+artifacts. This rendered ``rfc7952-data-api`` and ``rfc7952-data-util`` artifacts empty and thus these have been removed.
+See `YANGTOOLS-1489 <https://jira.opendaylight.org/browse/YANGTOOLS-1489>`__ for details.
+
+The interfaces supporting RFC8528 YANG schema mounts have been integrated into ``yang-data-api`` and ``yang-data-util``
+artifacts. This rendered ``rfc8528-data-api`` and ``rfc8528-data-util`` artifacts empty and thus these have been removed.
+See `YANGTOOLS-1172 <https://jira.opendaylight.org/browse/YANGTOOLS-1172>`__ for details.
+
+As part of these changes, following API changes have also been done in order to ease using these interfaces:
+* ``NormalizedNodeStreamWriterExtension`` has been renamed to ``NormalizedNodeStreamWriter.Extension``
+* ``StreamWriterMetadataExtension`` has been renamed to ``NormalizedNodeStreamWriter.MetadataExtension``
+* ``StreamWriterMountPointExtension`` has been renamed to ``NormalizedNodeStreamWriter.MountPointExtension``
+* ``MountPointIdentifier`` has been removed with ``NormalizedMountPoint`` exposing its ``MountPointLabel`` directly
+
+Finally, the result of ``NormalizedNodeStreamWriter`` is now a combined structure, ``NormalizationResult``, which combines
+a mandatory ``NormalizedNode`` data tree, an optional ``NormalizedMetadata`` and an optional ``NormalizedMountPoints`` tree.
+For the purposes of receiving this the result, ``NormalizedNodeResult`` has been replaced with ``NormalizationResultHolder``.
+
+``DataSchemaContextNode`` replaced with ``DataSchemaContext``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``yang.data.util.DataSchemaContextNode`` has been completely revamped and renamed to ``DataSchemaContext``. It is now an interface
+implemented completely internally, with a proper interface hierarchy. Implementations of these interfaces are given out by
+``DataSchemaContextTree``.  The resulting API is much easier to figure out and use, especially with proper documentation and naming
+not overlapping with other parts of YANG Tools.
+See `YANGTOOLS-1413 <https://jira.opendaylight.org/browse/YANGTOOLS-1413>`__ for details.
+
+``ExtensibleObject`` has been reworked
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This interface no longer exposes a ``ClassToInstanceMap``, but rather provides direct lookup and enumeration methods. Users need
+to be updated from performing
+
+  .. code-block:: java
+
+    ExtensibleObject obj;
+    var extension = obj.getExtensions().getInstance(ExtensionType.class);
+
+to instead doing
+
+  .. code-block:: java

 
 

-``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.
+    ExtensibleObject obj;
+    var extension = obj.extension(ExtensionType.class);
+
+See `YANGTOOLS-1509 <https://jira.opendaylight.org/browse/YANGTOOLS-1509>`__ for details.
+
+``UsesNode.getRefines()`` exposes only descendant paths
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The return type was changed to return ``Set<Descendant>`` instead of ``Map<Descendant, SchemaNode>``. Users relying on accessing
+target nodes need to perform the resolution themselves.
+See `YANGTOOLS-1518 <https://jira.opendaylight.org/browse/YANGTOOLS-1518>`__ for details.
+
+``YangTextSchemaSources`` is a ``CharSource``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``yang.model.api.repo.YangTextSchemaSource`` now operates on a stream of characters, not bytes. All users which instantiate sources
+from byte streams must specify the character set used.
+See `YANGTOOLS-1508 <https://jira.opendaylight.org/browse/YANGTOOLS-1508>`__ for details.

 
 
 MD-SAL Impacts
 --------------
 
 
 
 MD-SAL Impacts
 --------------
 

-``yang.binding.Enumeration`` renamed to ``yang.binding.EnumTypeObject``
+``InstanceIdentifierBuilder`` renamed to ``InstanceIdentifier.Builder``

 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-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.
-
-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.
-
-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.
-
-``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.
+A long-standing bug, where a ``KeyedInstanceIdentifier`` could not be safely returned from ``InstanceIdentifierBuilder`` was fixed.
+As part of this fix, ``InstanceIdentifierBuilder`` was renamed to be an inner class, ``InstanceIdentifier.Builder``. There is also
+a corresponding ``InstanceIdentifier.KeyedBuilder``. See `MDSAL-798 <https://jira.opendaylight.org/browse/MDSAL-798>`__ for details.

 
 

+``BindingReflections.getModuleInfo()`` has moved
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This reflection-based method was moved to ``BindingRuntimeHelpers`` class, as all its users already interact with
+``mdsal-binding-runtime-spi``. See `MDSAL-803 <https://jira.opendaylight.org/browse/MDSAL-803>`__ for details.

 
 

-Controller Impacts
-------------------
+Convenience model artifacts removed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The aggregating multi-module RFCs have been removed. Users declaring a dependency on any of ``rfc6991``, ``rfc8294``, ``rfc8342``,
+``rfc8345``, ``rfc8346``, ``rfc8348``, ``rfc8349``, ``rfc8519``, ``rfc8520``, ``rfc8542``, ``rfc8776`` or ``rfc8795`` need to now
+update these references to individual modules' artifacts.
+See `MDSAL-823 <https://jira.opendaylight.org/browse/MDSAL-823>`__ for details.
+
+``BindingMapping`` moved
+^^^^^^^^^^^^^^^^^^^^^^^^
+``binding.spec.naming.BindingMapping`` has been renamed and moved to ``yang.binding.contract.Naming``.
+See `MDSAL-804 <https://jira.opendaylight.org/browse/MDSAL-804>`__ for details.
+
+``IetfInetUtil.INSTANCE`` and ``IetfYangUtil.INSTANCE`` removed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``IetfInetUtil`` and ``IetfYangUtil`` have been refactored so they now expose static utility methods not encapsulated
+in an object instance. All references to ``INSTANCE`` need to be removed:
+
+  .. code-block:: java

 
 

-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.
+    byte[] bytes;
+    IetfYangUtil.INSTANCE.macAddressFor(bytes);

 
 

-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.
+becomes

 
 

-Improved datastore access and persistence protocols
+  .. code-block:: java
+
+    byte[] bytes;
+    IetfYangUtil.macAddressFor(bytes);
+
+See `MDSAL-804 <https://jira.opendaylight.org/browse/MDSAL-804>`__ for details.
+
+Binding ``Identifiable`` and ``Identifier`` renamed

 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-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.
+``yang.binding.Identifer`` has been renamed to ``yang.binding.Key`` and ``yang.binding.Identifiable`` has been renamed to
+``yang.binding.KeyAware``. This change prevents confusion with ``yangtools.concepts`` interfaces with the same name.
+See `MDSAL-830 <https://jira.opendaylight.org/browse/MDSAL-830>`__ for details.
+
+
+Controller Impacts
+------------------
+None.

 
 

diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index b48925ccabef4e302cb10aa4fae8276338a673b8..d65d3b4d9e326937f674b3704b7362fb37b7a520 100644 (file)
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -133,6 +133,7 @@ rebasing
 reconfigurable
 reconnection
 refactor
 reconfigurable
 reconnection
 refactor

+refactored

 refactoring
 referenceable
 reimplemented
 refactoring
 referenceable
 reimplemented