README.md


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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304


    Contents⊕
  
  
  API overview
  CLI
  
  Built-in help
  Diff
  Check
  Infer
  Validate
  
  Maven Enforcer Rule
  
  Checking a project's
  compatibility
  Checking a project's
  version
  
  Dumping details
  
  Checking against
  a well known version
  Filtering
  
  Maven dependency
  License
  

Version number changes implications are not always clearly
identified. Can I be sure this new minor version didn't break the public
API? As a library writer, how to continuously validate I don't break
binary compatibility?
semantic-versioning is a Java library allowing to
validate (using bytecode inspection) if library version numbers follows
Semantic Versioning principles as defined by [http://semver.org](Semantic Versioning). It
can check JAR files or classes to identify changes between versions and
validate if the new version number is correct according to semver.
semantic-versioning is available as an API, a command line tool and a maven
enforcer rule.

API overview
Semantic Versioning also provides an API for programmatically
validating your project's version number.
final File previousJar = ...;
final File currentJar = ...;
        
final Comparer comparer = new Comparer(previousJar, currentJar, ..., ...);
final Delta delta = comparer.diff();

final String compatibilityType = ...;

//Validates that computed and provided compatibility type are compatible.
final Delta.CompatibilityType expectedCompatibilityType = Delta.CompatibilityType.valueOf(compatibilityType);
final Delta.CompatibilityType detectedCompatibilityType = delta.computeCompatibilityType();
if (detectedCompatibilityType.compareTo(expectedCompatibilityType) > 0) {
  //Not compatible.
}

//Provide version number for previous and current Jar files.
final Version previous = Version.parse(...);
final Version current = Version.parse(...);

//Validates that current version number is valid based on semantic versioning principles.
final boolean compatible = delta.validate(previous, current);

CLI
This simple command line tool looks at Java JAR files and determine
API changes.
Built-in help
% java -jar semver.jar --help
Semantic Version validator.

Usage: semver [options]

Options:
  --base-jar JAR          The base jar.
  --base-version VERSION  Version of the base jar (given with --base-jar).
  --check,-c              Check the compatibility of two jars.
  --diff,-d               Show the differences between two jars.
  --excludes EXCLUDE;...  Semicolon separated list of full qualified class names
                          to be excluded.
  --help,-h               Show this help and exit.
  --includes INCLUDE;...  Semicolon separated list of full qualified class names
                          to be included.
  --infer,-i              Infer the version of the new jar based on the previous
                          jar.
  --new-jar JAR           The new jar.
  --new-version VERSION   Version of the new jar (given with --new-jar).
  --validate,-v           Validate that the versions of two jars fulfil the
                          semver specification.
Diff
Dump all changes between two JARs on standard output.
% java -jar semver.jar --diff --base-jar previousJar --new-jar current.jar
Class org.project.MyClass
 Added Class 
Class org.project.MyClass2
 Added Method method1
 Removed Field field1
 Changed Field field2 removed: final
Check
Check compatibility type between two JARs.
% java -jar semver.jar --check --base-jar previousJar --new-jar current.jar
BACKWARD_COMPATIBLE_IMPLEMENTER
Infer
Infer JAR version based on a previously versioned JAR.
% java -jar semver.jar --infer --base-version 1.0.0 --base-jar previous.jar --new-jar current.jar
1.0.1
Validate
Validate JAR version based on a previously versioned JAR.
% java -jar semver.jar --validate --base-version 1.0.0 --base-jar previous.jar --new-version 1.0.1 --new-jar current.jar
true

Maven Enforcer Rule
The enforcer rule offers a rule for checking project's version
against a previously released artifact.
Checking a project's
compatibility
In order to check your project's compatibility, you must add the
enforcer rule as a dependency to the maven-enforcer-plugin and then
configure the maven-enforcer-plugin to run the rule:
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <artifactId>maven-enforcer-plugin</artifactId>
        <version>1.0.1</version>
        ...
        <dependencies>
            ...
            <dependency>
                <groupId>org.semver</groupId>
                <artifactId>enforcer-rule</artifactId>
                <version>0.9.17</version>
            </dependency>
            ...
        </dependencies>
        ...
        <executions>
           ....
          <execution>
            <id>check</id>
            <phase>verify</phase>
            <goals>
              <goal>enforce</goal>
            </goals>
            <configuration>
              <rules>
                <requireBackwardCompatibility implementation="org.semver.enforcer.RequireBackwardCompatibility">
                  <compatibilityType>BACKWARD_COMPATIBLE_IMPLEMENTER</compatibilityType>
                </requireBackwardCompatibility>
              </rules>
            </configuration>
          </execution>
          ...
        </executions>
        ...
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
Once you have configured your project, maven-enforcer will be able to
throw a build error if current version is not backward compatible with
last released one.
You can force strict checking (i.e. compatibility type must exactly
match specified one):
<configuration>
  <rules>
    <requireBackwardCompatibility implementation="org.semver.enforcer.RequireBackwardCompatibility">
      ...
      <strictChecking>true</strictChecking>
      ...
    </requireBackwardCompatibility>
  </rules>
</configuration>
Checking a project's version
In order to check your project's version, you must add the enforcer
rule as a dependency to the maven-enforcer-plugin and then configure the
maven-enforcer-plugin to run the rule:
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <artifactId>maven-enforcer-plugin</artifactId>
        <version>1.0.1</version>
        ...
        <dependencies>
            ...
            <dependency>
                <groupId>org.semver</groupId>
                <artifactId>enforcer-rule</artifactId>
                <version>0.9.12</version>
            </dependency>
            ...
        </dependencies>
        ...
        <executions>
           ....
          <execution>
            <id>check</id>
            <phase>verify</phase>
            <goals>
              <goal>enforce</goal>
            </goals>
            <configuration>
              <rules>
                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance" />
              </rules>
            </configuration>
          </execution>
          ...
        </executions>
        ...
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
Once you have configured your project, maven-enforcer will be able to
throw a build error if current version follows semantic versioning
principles.
Dumping details
Dump details of detected changes:
<configuration>
  <rules>
    <require...>
      ...
      <dumpDetails>true</dumpDetails>
      ...
    </require...>
  </rules>
</configuration>
Checking against a well
known version
You can force check with a well known version:
<configuration>
  <rules>
    <require...>
      ...
      <previousVersion>1.0.0</previousVersion>
      ...
    </require...>
  </rules>
</configuration>
Filtering
Both rules allow to filter classes/packages:
<require...>
  ...
  <includes>
    <include>org.project.MyClass</include>
    <include>org.project.internal</include>
  </includes>
  <excludes>
    <exclude>org.project.MyClass</exclude>
    <exclude>org.project.internal</exclude>
  </excludes>
  ...
</require...>
Maven dependency
<dependency>
    <groupId>org.semver</groupId>
    <artifactId>enforcer-rule</artifactId>
    <version>0.9.17</version>
</dependency>
License
Released under Apache 2
license.