diff options
| -rw-r--r-- | yang-comparator/README.md | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/yang-comparator/README.md b/yang-comparator/README.md new file mode 100644 index 0000000..3b72db6 --- /dev/null +++ b/yang-comparator/README.md @@ -0,0 +1,197 @@ +# YANG Comparator + +Yang comparator is a tool which can compare two versions of yang releases. It can help users to identify the differences of the two versions. +It can work as a standalone application or as a plugin of [YANG compiler](https://github.com/onap/modeling-yang-kit/tree/master/yang-compiler). + +Yang comparator provides three main functions between two versions: + +- compare statements +- compare tree +- check the compatibility + +## Compare statements +Compare the statements of two yang release versions. + +It will identify the statements which could be added, changed or deleted for every yang files between the previous version and current version. +These differences are all textual differences, not the effective differences. For example: + +Previous statements: + +```yang +leaf foo { + type string; +} +``` + +Current statements: + +```yang +leaf foo { + type string; + mandatory false; +} +``` + +The difference will be "mandatory false" is added, even though the previous leaf foo is 'mandatory false' by default. + +## Compare tree + +Compare the schema tree of two yang release versions. + +It will identify which schema node paths are added, changed or deleted, and which schema node paths are changed to be deprecated or obsolete. +These differences are effective differences: + +- All config missed will be treated to be default value +- All status missed will be treated to be current +- All mandatory missed will be treated to be false +- All min-elements missed will be treated to be 0 +- All max-elements missed will be treated to be unbounded +- All ordered-by missed will be treated to be system + +For example: + +Previous statements: + +```yang + leaf foo { + type string; + } +``` + +Current statements: + +```yang + leaf foo { + type string; + mandatory true; + } +``` + +The difference is changing 'mandatory' from false to true even though the previous statements have no 'mandatory'. + +## Check compatibility + +This function will output the compatibility results after comparing two yang release versions. + +It allows users to define their own compatible-check rules, if no self-defined rule is provide, it will use the default one. + +compatible-check rule is an XML file, every rule MUST be defined by the XML tags listed below: + +- rules: the root element of the rule XML file +- rule: a container for rule, it will define a compatibility rule +- rule-id: the identifier for a rule +- statements: the statements what the rule is applied +- statement: the statement what the rule is applied +- condition: the change type of statement to be matched. The change type maybe the values listed below: + 1. [x] added: any sub statement is added. + 2. [x] deleted: any sub statement is deleted. + 3. [x] changed: the meaning has been changed,for example, builtin-type changed for type,value changed for enumeration. + 4. [x] mandatory-added: add mandatory schema node. + 5. [x] sequence-changed: sequence-changed. + 6. [x] expand: expand the scope, for range,it means larger range, for length, it means larger length, for fraction-digits, + it means a lower value, for min-elements, it means a lower value, for max-elements, it means a higher value, + for mandatory, it means from true to false, for config, it means from false to true + for unique, it means one or more attributes are deleted. + 7. [x] reduce: reduce the scope, for range,it means smaller range, for length, it means smaller length, for fraction-digits, + it means a higher value, for min-elements, it means a higher value, for max-elements, it means a lower value, + for mandatory, it means from false to true, for config, it means from true to false, + for unique, it means new attributes are added. + 8. [x] integer-type-changed: for example type from int8 to int16,it is treated non-backward-compatible by default. + 9. [x] any: match any changes + 10. [x] ignore: ignore any changes, it means backward-compatibility for any changes. + +- except-condition: condition what will be not matched. +- compatible: compatibility conclusion, non-backward-compatible or backward-compatible are accepted value. +- description: the description of this rule. + +## Installation + +### Prerequisites + +JDK or JRE 1.8 or above + +### Obtain code + +```shell +git clone "https://gerrit.onap.org/r/modeling/yang-kit" +``` + +### Build code + +```shell +cd yang-kit/yang-comparator/ +mvn clean install +``` + +It will generate yang-comparator-x.y.z-SNAPSHOT.jar and libs directory under the directory target. + +Copy yang-comparator-x.y.z-SNAPSHOT.jar and libs to anywhere in your computer. + +## Usage + +### Standalone application + +```shell +java -jar yang-comparator-x.y.z-SNAPSHOT.jar _arguments_ + +usage: -left --y {yang file or dir]} [--dep {dependency file or dir}] [--cap {capabilities.xml}] + -right --y {yang file or dir]} [--dep {dependency file or dir}] [--cap {capabilities.xml}] + -o {output.xml} + {-tree | -stmt [--filter filter.xml] | -compatible-check [--rule rule.xml] [--filter filter.xml]} +``` + +#### Example + +Download yang files of network-router from https://github.com/Huawei/yang. +There are many different versions of yang files in this repo and you can choose any two versions to do the comparation. + +```shell +# Get statement differences +java -jar yang-comparator-x.y.z-SNAPSHOT.jar -left --y yang/8.20.10 -right --y yang/8.21.0 -o out/diff_stmt.xml -stmt + +# Get schema node path differences +java -jar yang-comparator-x.y.z-SNAPSHOT.jar -left --y yang/8.20.10 -right --y yang/8.21.0 -o out/diff_tree.xml -tree + +# Get compatibility results +java -jar yang-comparator-x.y.z-SNAPSHOT.jar -left --y yang/8.20.10 -right --y yang/8.21.0 -o out/compatibility.xml -compatible-check + +# Get compatibility with rule result +java -jar yang-comparator-x.y.z-SNAPSHOT.jar -left --y yang/8.20.10 -right --y yang/8.21.0 -o out/compatibility_rule.xml -compatible-check --rule rules.xml +``` + +### Plugin of YANG compiler + +1. Copy `src/resources/plugins.json` to YANG compiler application directory and modify the plugins.json to + indicate the class-path of YANG comparator (the class-path MUST point to the directory where yang-comparator-x.y.z-SNAPSHOT.jar lives in). + +2. Set the build option (in build.json). The description of plugin parameters can be found in plugins.json. e.g. + +```json +{ + "build": { + "yang": "yang/new", + "plugin": [ + { + "name": "yang_comparator", + "parameter": [ + { + "name": "old-yang", + "value": "yang/old" + }, + { + "name": "compare-type", + "value": "compatible-check" + }, + { + "name": "result", + "value": "yang/result_tree.xml" + } + ] + } + ] + } +} +``` + +3. Run compiler, see [YANG compiler](https://github.com/onap/modeling-yang-kit/tree/master/yang-compiler). + |