docs/release-notes/projects/yangtools.rst

   1 ==========
   2 YANG Tools
   3 ==========
   4
   5 Major Features
   6 ==============
   7
   8 Oxgeyn release marks the eightth release of YANG Tools components. The focus
   9 of this release was to clean up deprecated APIs and perform maintenance
  10 which requires breaking API compatibility -- hence producing a 2.0.x release
  11 train.
  12
  13 Major items delivered are:
  14 * Split up yang-parser-impl, allowing components to be plugged more cleanly
  15 * Remove use of Guava's Optional in favor of Java 8's equivalent
  16 * Define yang-parser-api
  17 * Mandatory leaves are enforced by default
  18 * RFC7951-compliant JSON codec
  19 * Features have been split into stable and experimental
  20 * Old XML parser has been removed
  21 * YANG model revisions are represented via a dedicated class, not Date
  22 * YANG type empty is represented as a dedicated class, not Void
  23
  24 odl-triemap
  25 -----------
  26
  27 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-triemap/pom.xml;hb=refs/tags/v2.0.1
  28 * **Feature Description:** to install concurrent-hash-trie-based Map implementation
  29 * **Top Level:** Yes
  30 * **User Facing:** No
  31 * **Experimental:** No
  32 * **CSIT Test:** System test waiver request pending.
  33
  34 odl-yangtools-codec
  35 -------------------
  36
  37 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-yangtools-common/pom.xml;hb=refs/tags/v2.0.1
  38 * **Feature Description:** to install JSON and XML parsers
  39 * **Top Level:** Yes
  40 * **User Facing:** No
  41 * **Experimental:** No
  42 * **CSIT Test:** System test waiver request pending.
  43
  44 odl-yangtools-common
  45 --------------------
  46
  47 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-yangtools-common/pom.xml;hb=refs/tags/v2.0.1
  48 * **Feature Description:** to install common concepts and utilities.
  49 * **Top Level:** Yes
  50 * **User Facing:** No
  51 * **Experimental:** No
  52 * **CSIT Test:** System test waiver request pending.
  53
  54 odl-yangtools-data-api
  55 ----------------------
  56
  57 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-yangtools-data-api/pom.xml;hb=refs/tags/v2.0.1
  58 * **Feature Description:** to install YANG Data APIs.
  59 * **Top Level:** Yes
  60 * **User Facing:** No
  61 * **Experimental:** No
  62 * **CSIT Test:** System test waiver request pending.
  63
  64 odl-yangtools-data
  65 ------------------
  66
  67 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-yangtools-data/pom.xml;hb=refs/tags/v2.0.1
  68 * **Feature Description:** to install YANG Data implementation.
  69 * **Top Level:** Yes
  70 * **User Facing:** No
  71 * **Experimental:** No
  72 * **CSIT Test:** System test waiver request pending.
  73
  74 odl-yangtools-export
  75 --------------------
  76
  77 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-yangtools-export/pom.xml;hb=refs/tags/v2.0.1
  78 * **Feature Description:** to install YANG model export utilities.
  79 * **Top Level:** Yes
  80 * **User Facing:** No
  81 * **Experimental:** No
  82 * **CSIT Test:** System test waiver request pending.
  83
  84 odl-yangtools-parser-api
  85 ------------------------
  86
  87 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-yangtools-parser-api/pom.xml;hb=refs/tags/v2.0.1
  88 * **Feature Description:** to install YANG model APIs
  89 * **Top Level:** Yes
  90 * **User Facing:** No
  91 * **Experimental:** No
  92 * **CSIT Test:** System test waiver request pending.
  93
  94 odl-yangtools-parser
  95 --------------------
  96
  97 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-yangtools-parser/pom.xml;hb=refs/tags/v2.0.1
  98 * **Feature Description:** to install YANG Parser
  99 * **Top Level:** Yes
 100 * **User Facing:** No
 101 * **Experimental:** No
 102 * **CSIT Test:** https://jenkins.opendaylight.org/releng/view/yangtools/job/yangtools-csit-1node-periodic-system-only-oxygen/
 103
 104 odl-yangtools-xpath
 105 -------------------
 106
 107 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-yangtools-xpath/pom.xml;hb=refs/tags/v2.0.1
 108 * **Feature Description:** to install XPath evaluation engine
 109 * **Top Level:** Yes
 110 * **User Facing:** No
 111 * **Experimental:** No
 112 * **CSIT Test:** System test waiver request pending.
 113
 114 odl-exp-objcache
 115 ----------------
 116
 117 * **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;a=blob_plain;f=features/odl-exp-objcache/pom.xml;hb=refs/tags/v2.0.1
 118 * **Feature Description:** to install Object Cache APIs and implementation
 119 * **Top Level:** Yes
 120 * **User Facing:** No
 121 * **Experimental:** Yes
 122 * **CSIT Test:** System test waiver request pending.
 123
 124 Documentation
 125 =============
 126 * **Developer Guide(s):**
 127
 128   * :ref:`yangtools-developer-guide`
 129
 130 Security Considerations
 131 =======================
 132
 133 * YANG Tools libraries are designed to be embedded and not to be a stand-alone
 134   application so security concerns need to be addressed by the application
 135   using this library.
 136
 137 Quality Assurance
 138 =================
 139
 140 * `Link to Sonar Report <https://sonar.opendaylight.org/dashboard?id=org.opendaylight.yangtools%3Ayangtools-aggregator>`_
 141   Test coverage 62.3%, which constitutes a drop by 12%. This is caused by the parser being more modular, hence tests which
 142   previously accounted to code coverage are no longer counted. We will address this with targeted unit tests if following
 143   releases.
 144 * `Link to CSIT Jobs
 145   <https://jenkins.opendaylight.org/releng/view/yangtools/job/yangtools-csit-1node-periodic-system-only-oxygen/>`_
 146
 147 Migration
 148 ---------
 149
 150 * This release constitutes a major shift in all APIs exposed by yangtools. Code
 151   users need to adjust their feature refences and adjust to changed method
 152   signatures. Most users should not be impacted as they should be interacting
 153   with MD-SAL.
 154
 155 Compatibility
 156 -------------
 157
 158 * Release is not compatible with the previous one. The APIs changed are too numerous to list here.
 159
 160 * No configuration changes.
 161
 162 * Behavior changes:
 163   * Mandatory leaf presence is enforced by default
 164   * Pattern invert-match modifier is honored in both JSON and XML codecs
 165
 166 Bugs Fixed
 167 ----------
 168
 169 * List of fixed `Bugs <https://jira.opendaylight.org/issues/?jql=project%20%3D%20YANGTOOLS%20AND%20fixVersion%20%3D%202.0.0%20OR%20fixVersion%20%3D%202.0.1>`
 170
 171 Known Issues
 172 ------------
 173
 174 * List of open `Bugs <https://jira.opendaylight.org/issues/?jql=project%20%3D%20YANGTOOLS%20AND%20affectedVersion%20%3D%202.0.1?`
 175
 176 End-of-life
 177 ===========
 178
 179 * odl-exp-objcache is marked as experimental and will be removed in the next
 180   major (3.0.0) release.
 181
 182 * This release contains deprecated API elements in all code artifacts. These
 183   will be removed in the next major (3.0.0) release.
 184
 185 * All API elements are expected to remain compatible for at least the duration
 186   of Fluorine release cycle.
 187
 188 Standards
 189 =========
 190
 191 * YANG and YIN parser processing according to
 192   `RFC 6020 <https://tools.ietf.org/html/rfc6020>`_,
 193   `RFC 6536 <https://tools.ietf.org/html/rfc6536>`_,
 194   `RFC 7950 <https://tools.ietf.org/html/rfc7950>`_,
 195   `RFC 7952 <https://tools.ietf.org/html/rfc7950>`_ and
 196   `RFC 8040 <https://tools.ietf.org/html/rfc8040>`_
 197 * XML parser for YANG-modeled data according to
 198   `RFC 6020 <https://tools.ietf.org/html/rfc6020>`_ and
 199   `RFC 7950 <https://tools.ietf.org/html/rfc7950>`_.
 200 * JSON parser for YANG-modeled data according to
 201   `RFC 7951 <https://tools.ietf.org/html/rfc7951>`_
 202
 203 Release Mechanics
 204 =================
 205
 206 * `Link to the release plan <https://wiki.opendaylight.org/view/Simultaneous_Release:Oxygen_Release_Plan>`_