1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
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).
|
