Added requireBackwardCompatibility rule.

7 files changed, 499 insertions, 35 deletions

diff --git a/enforcer-rule/src/main/java/org/semver/enforcer/CheckVersionRule.java b/enforcer-rule/src/main/java/org/semver/enforcer/AbstractEnforcerRule.java
index e819ca9..0fd0b36 100644
--- a/enforcer-rule/src/main/java/org/semver/enforcer/CheckVersionRule.java
+++ b/enforcer-rule/src/main/java/org/semver/enforcer/AbstractEnforcerRule.java
@@ -47,12 +47,10 @@ import org.semver.Version;
 
 /**
  * 
- * Checks {@link Version} for current {@link Artifact} compared to a previous {@link Artifact}.
- * <br />
- * Fails if {@link Version} semantic is not respected.
+ * Abstract {@link EnforcerRule} implementation providing facilities for compatibility checking.
  * 
  */
-public final class CheckVersionRule implements EnforcerRule {
+public abstract class AbstractEnforcerRule implements EnforcerRule {
 
     private static final String SNAPSHOT_VERSION_SUFFIX = "-SNAPSHOT";
     
@@ -118,7 +116,7 @@ public final class CheckVersionRule implements EnforcerRule {
                 final List<ArtifactVersion> availableVersions = getAvailableReleasedVersions(artifactMetadataSource, project, localRepository);
                 
                 if (availableVersions.isEmpty()) {
-                    helper.getLog().info("No previously released version. Backward compatibility check not performed.");
+                    helper.getLog().warn("No previously released version. Backward compatibility check not performed.");
                     
                     return;
                 }
@@ -150,22 +148,26 @@ public final class CheckVersionRule implements EnforcerRule {
         try {
             final Comparer comparer = new Comparer(previousJar, currentJar, extractFilters(this.includes), extractFilters(this.excludes));
             final Delta delta = comparer.diff();
-            final boolean compatible = delta.validate(previous, current);
-            if (!compatible) {
-                if (this.dumpDetails) {
-                    Dumper.dump(delta);
-                }
-                throw new EnforcerRuleException("Current codebase incompatible with version <"+current+">. Version should be at least <"+delta.infer(previous)+">.");
-            }
+
+            enforce(delta, previous, current);
         } catch (IOException e) {
             throw new EnforcerRuleException("Exception while checking compatibility: "+e.toString(), e);
         }
     }
 
+    protected abstract void enforce(final Delta delta, final Version previous, final Version current) throws EnforcerRuleException;
+    
+    protected final void fail(final Delta delta, final String message) throws EnforcerRuleException {
+        if (this.dumpDetails) {
+            Dumper.dump(delta);
+        }
+        throw new EnforcerRuleException(message);
+    }
+    
     protected final String getVersion(final Artifact artifact) {
         final String version = artifact.getVersion();
-        if (version.contains(CheckVersionRule.SNAPSHOT_VERSION_SUFFIX)) {
-            return version.substring(0, version.indexOf(CheckVersionRule.SNAPSHOT_VERSION_SUFFIX));
+        if (version.contains(AbstractEnforcerRule.SNAPSHOT_VERSION_SUFFIX)) {
+            return version.substring(0, version.indexOf(AbstractEnforcerRule.SNAPSHOT_VERSION_SUFFIX));
         }
         return version;
     }
@@ -175,7 +177,7 @@ public final class CheckVersionRule implements EnforcerRule {
      * @return true if specified version is a snapshot version
      */
     protected final boolean isSnapshotVersion(final ArtifactVersion artifactVersion) {
-        return artifactVersion.toString().endsWith(CheckVersionRule.SNAPSHOT_VERSION_SUFFIX);
+        return artifactVersion.toString().endsWith(AbstractEnforcerRule.SNAPSHOT_VERSION_SUFFIX);
     }
     
     /**
diff --git a/enforcer-rule/src/main/java/org/semver/enforcer/RequireBackwardCompatibility.java b/enforcer-rule/src/main/java/org/semver/enforcer/RequireBackwardCompatibility.java
new file mode 100644
index 0000000..57050f7
--- /dev/null
+++ b/enforcer-rule/src/main/java/org/semver/enforcer/RequireBackwardCompatibility.java
@@ -0,0 +1,61 @@
+/**
+ * This software is licensed under the Apache 2 license, quoted below.
+ *
+ * Copyright 2010 Julien Eluard
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     [http://www.apache.org/licenses/LICENSE-2.0]
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package org.semver.enforcer;
+
+import org.apache.maven.artifact.Artifact;
+import org.apache.maven.enforcer.rule.api.EnforcerRuleException;
+import org.semver.Delta;
+import org.semver.Version;
+
+/**
+ * 
+ * Checks {@link Version} for current {@link Artifact} compared to a previous {@link Artifact}.
+ * <br />
+ * Fails if current version is not backward compatible with previous one. {@link Delta.CompatibilityType} level can be specified.
+ * 
+ */
+public final class RequireBackwardCompatibility extends AbstractEnforcerRule {
+    
+    /**
+     * Compatibility type expected. Must be one of {@link Delta.CompatibilityType} enum values.
+     * 
+     * @parameter
+     */
+    private String compatibilityType;
+
+    @Override
+    protected void enforce(final Delta delta, final Version previous, final Version current) throws EnforcerRuleException {
+        if (this.compatibilityType == null) {
+            throw new IllegalArgumentException("A value for compatibilityType attribute must be provided.");
+        }
+        
+        final Delta.CompatibilityType expectedCompatibilityType;
+        try {
+            expectedCompatibilityType = Delta.CompatibilityType.valueOf(this.compatibilityType);
+        } catch (IllegalStateException e) {
+            throw new EnforcerRuleException("Compatibility type value must be one of "+Delta.CompatibilityType.values());
+        }
+
+        final Delta.CompatibilityType detectedCompatibilityType = delta.computeCompatibilityType();
+        if (detectedCompatibilityType != expectedCompatibilityType) {
+            fail(delta, "Current codebase is not backward compatible ("+this.compatibilityType+") with version <"+previous+">. Compatibility type has been detected as <"+detectedCompatibilityType+">");
+        }
+    }
+
+}
diff --git a/enforcer-rule/src/main/java/org/semver/enforcer/RequireSemanticVersioningConformance.java b/enforcer-rule/src/main/java/org/semver/enforcer/RequireSemanticVersioningConformance.java
new file mode 100644
index 0000000..608557e
--- /dev/null
+++ b/enforcer-rule/src/main/java/org/semver/enforcer/RequireSemanticVersioningConformance.java
@@ -0,0 +1,43 @@
+/**
+ * This software is licensed under the Apache 2 license, quoted below.
+ *
+ * Copyright 2010 Julien Eluard
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     [http://www.apache.org/licenses/LICENSE-2.0]
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package org.semver.enforcer;
+
+import org.apache.maven.artifact.Artifact;
+import org.apache.maven.enforcer.rule.api.EnforcerRuleException;
+import org.semver.Delta;
+import org.semver.Version;
+
+/**
+ * 
+ * Checks {@link Version} for current {@link Artifact} compared to a previous {@link Artifact}.
+ * <br />
+ * Fails if {@link Version} semantic is not respected.
+ * 
+ */
+public final class RequireSemanticVersioningConformance extends AbstractEnforcerRule {
+
+    @Override
+    protected void enforce(final Delta delta, final Version previous, final Version current) throws EnforcerRuleException {
+        final boolean compatible = delta.validate(previous, current);
+        if (!compatible) {
+            fail(delta, "Current codebase is incompatible with version <"+previous+">. Version should be at least <"+delta.infer(previous)+">.");
+        }
+    }
+
+}
diff --git a/enforcer-rule/src/site/apt/examples/backward-compatibility.apt.vm b/enforcer-rule/src/site/apt/examples/backward-compatibility.apt.vm
new file mode 100644
index 0000000..bfbf818
--- /dev/null
+++ b/enforcer-rule/src/site/apt/examples/backward-compatibility.apt.vm
@@ -0,0 +1,304 @@
+#*
+ * This software is licensed under the Apache 2 license, quoted below.
+ *
+ * Copyright 2010 Julien Eluard
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     [http://www.apache.org/licenses/LICENSE-2.0]
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ *#
+
+Checking a project's compatibility against older releases 
+
+* Basic example
+
+  In order to check your project's compatibility against an older release, you must add the enforcer rule as a dependency to
+  the maven-enforcer-plugin and then configure your the maven-enforcer-plugin to run the rule.
+
+  By default current artifact will be checked against most recently released version (retrieved from either local or one of configured remote repositories).
+
+---
+<project>
+  ...
+  <build>
+    ...
+    <plugins>
+      ...
+      <plugin>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>1.0-beta-1</version>
+        ...
+        <dependencies>
+            ...
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>${project.artifactId}</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            ...
+        </dependencies>
+        ...
+        <executions>
+           ....
+          <execution>
+            <id>check-version</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>
+---
+
+* Checking against a specific released version
+
+  You can check your project against a specific released version:
+
+---
+<project>
+  ...
+  <build>
+    ...
+    <plugins>
+      ...
+      <plugin>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>1.0-beta-1</version>
+        ...
+        <dependencies>
+            ...
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>${project.artifactId}</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            ...
+        </dependencies>
+        ...
+        <executions>
+           ....
+          <execution>
+            <id>check-version</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>enforce</goal>
+            </goals>
+            <configuration>
+              <rules>
+                <requireBackwardCompatibility implementation="org.semver.enforcer.RequireBackwardCompatibility">
+                  ...
+                  <compatibilityType>BACKWARD_COMPATIBLE_IMPLEMENTER</compatibilityType>
+                  <previousVersion>1.0.0</previousVersion>
+                  ...
+                </requireBackwardCompatibility>
+              </rules>
+            </configuration>
+          </execution>
+          ...
+        </executions>            
+        ...
+      </plugin>
+      ...
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
+---
+
+* Including classes 
+
+  By default all classes will be considered during checking process. You might want to only check a subset of classes/packages. This is achieved by specifying <<<includes>>>.
+
+---
+<project>
+  ...
+  <build>
+    ...
+    <plugins>
+      ...
+      <plugin>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>1.0-beta-1</version>
+        ...
+        <dependencies>
+            ...
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>${project.artifactId}</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            ...
+        </dependencies>
+        ...
+        <executions>
+           ....
+          <execution>
+            <id>check-version</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>enforce</goal>
+            </goals>
+            <configuration>
+              <rules>
+                <requireBackwardCompatibility implementation="org.semver.enforcer.RequireBackwardCompatibility">
+                  ...
+                  <compatibilityType>BACKWARD_COMPATIBLE_IMPLEMENTER</compatibilityType>
+                  <includes>
+                    <include>org.project.MyClass</include>
+                  </includes>
+                  ...
+                </requireBackwardCompatibility>
+              </rules>
+            </configuration>
+          </execution>
+          ...
+        </executions>            
+        ...
+      </plugin>
+      ...
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
+---
+
+  We can specify multiple <includes> classes or packages. For example, to include <<<org.project.MyClass>>> class and <<<org.project.internal>>> package you would use a configuration like:
+
+---
+<project>
+  ...
+  <build>
+    ...
+    <plugins>
+      ...
+      <plugin>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>1.0-beta-1</version>
+        ...
+        <dependencies>
+            ...
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>${project.artifactId}</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            ...
+        </dependencies>
+        ...
+        <executions>
+           ....
+          <execution>
+            <id>check-version</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>enforce</goal>
+            </goals>
+            <configuration>
+              <rules>
+                <requireBackwardCompatibility implementation="org.semver.enforcer.RequireBackwardCompatibility">
+                  ...
+                  <compatibilityType>BACKWARD_COMPATIBLE_IMPLEMENTER</compatibilityType>
+                  <includes>
+                    <include>org.project.MyClass</include>
+                    <include>org.project.internal</include>
+                  </includes>
+                  ...
+                </requireBackwardCompatibility>
+              </rules>
+            </configuration>
+          </execution>
+          ...
+        </executions>            
+        ...
+      </plugin>
+      ...
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
+---
+
+* Excluding classes 
+
+  You may also want to exclude some classes/packages. For instance internal code might evolve independently from published API. This is achieved by specifying <<<excludes>>>.
+
+---
+<project>
+  ...
+  <build>
+    ...
+    <plugins>
+      ...
+      <plugin>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>1.0-beta-1</version>
+        ...
+        <dependencies>
+            ...
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>${project.artifactId}</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            ...
+        </dependencies>
+        ...
+        <executions>
+           ....
+          <execution>
+            <id>check-version</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>enforce</goal>
+            </goals>
+            <configuration>
+              <rules>
+                <requireBackwardCompatibility implementation="org.semver.enforcer.RequireBackwardCompatibility">
+                  ...
+                  <compatibilityType>BACKWARD_COMPATIBLE_IMPLEMENTER</compatibilityType>
+                  <excludes>
+                    <exclude>org.project.MyClass</exclude>
+                  </excludes>
+                  ...
+                </requireBackwardCompatibility>
+              </rules>
+            </configuration>
+          </execution>
+          ...
+        </executions>            
+        ...
+      </plugin>
+      ...
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
+---
diff --git a/enforcer-rule/src/site/apt/examples/checking-version.apt.vm b/enforcer-rule/src/site/apt/examples/semantic-versioning-conformance.apt.vm
index 328abea..fdfd7dd 100644
--- a/enforcer-rule/src/site/apt/examples/checking-version.apt.vm
+++ b/enforcer-rule/src/site/apt/examples/semantic-versioning-conformance.apt.vm
@@ -56,7 +56,7 @@ Checking a project's version against older releases
             </goals>
             <configuration>
               <rules>
-                <checkVersionRule implementation="org.semver.enforcer.CheckVersionRule" />
+                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance" />
               </rules>
             </configuration>
           </execution>
@@ -107,11 +107,11 @@ Checking a project's version against older releases
             </goals>
             <configuration>
               <rules>
-                <checkVersionRule implementation="org.semver.enforcer.CheckVersionRule">
+                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance">
                   ...
                   <previousVersion>1.0.0</previousVersion>
                   ...
-                </checkVersionRule>
+                </requireSemanticVersioningConformance>
               </rules>
             </configuration>
           </execution>
@@ -162,13 +162,13 @@ Checking a project's version against older releases
             </goals>
             <configuration>
               <rules>
-                <checkVersionRule implementation="org.semver.enforcer.CheckVersionRule">
+                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance">
                   ...
                   <includes>
                     <include>org.project.MyClass</include>
                   </includes>
                   ...
-                </checkVersionRule>
+                </requireSemanticVersioningConformance>
               </rules>
             </configuration>
           </execution>
@@ -217,14 +217,14 @@ Checking a project's version against older releases
             </goals>
             <configuration>
               <rules>
-                <checkVersionRule implementation="org.semver.enforcer.CheckVersionRule">
+                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance">
                   ...
                   <includes>
                     <include>org.project.MyClass</include>
                     <include>org.project.internal</include>
                   </includes>
                   ...
-                </checkVersionRule>
+                </requireSemanticVersioningConformance>
               </rules>
             </configuration>
           </execution>
@@ -275,13 +275,13 @@ Checking a project's version against older releases
             </goals>
             <configuration>
               <rules>
-                <checkVersionRule implementation="org.semver.enforcer.CheckVersionRule">
+                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance">
                   ...
                   <excludes>
                     <exclude>org.project.MyClass</exclude>
                   </excludes>
                   ...
-                </checkVersionRule>
+                </requireSemanticVersioningConformance>
               </rules>
             </configuration>
           </execution>
diff --git a/enforcer-rule/src/site/apt/index.apt b/enforcer-rule/src/site/apt/index.apt
index 9a22674..2887116 100644
--- a/enforcer-rule/src/site/apt/index.apt
+++ b/enforcer-rule/src/site/apt/index.apt
@@ -23,15 +23,10 @@ Semantic Versioning Enforcer Rule
 
 * Rules Overview
 
-  The Semantic Versioning Enforcer Rule has the following rule.
+  The Semantic Versioning Enforcer Rule has the following rules.
 
-  * <<<checkVersionRule>>> checks a project version number against an older release.
+  * {{{./examples/semantic-versioning-conformance.html}requireSemanticVersioningConformance}} checks a project version number against an older release.
 
-* Examples
-
-  To provide you with better understanding of some usages of Semantic Versioning Enforcer Rule,
-  you can take a look into the following example:
-
-  * {{{./examples/checking-version.html}Checking a project's version against an older release}}
+  * {{{./examples/backward-compatibility.html}requireBackwardCompatibility}} checks a project artifact against an older release.
 
   []
diff --git a/enforcer-rule/src/site/apt/usage.apt.vm b/enforcer-rule/src/site/apt/usage.apt.vm
index 9a21ac0..fc9c196 100644
--- a/enforcer-rule/src/site/apt/usage.apt.vm
+++ b/enforcer-rule/src/site/apt/usage.apt.vm
@@ -22,6 +22,65 @@ Usage
 
 * Basic Usage
 
+** 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-beta-1</version>
+        ...
+        <dependencies>
+            ...
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>${project.artifactId}</artifactId>
+                <version>${project.version}</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. 
+
+  Some more detailed {{{./examples/backward-compatibility.html}examples}} of the <<<requireBacwardCompatibility>>> rule.
+
+
 ** Checking a project's version
 
   In order to check your project's version, you must add the enforcer rule as a dependency to
@@ -58,7 +117,7 @@ Usage
             </goals>
             <configuration>
               <rules>
-                <checkVersionRule implementation="org.semver.enforcer.CheckVersionRule" />
+                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance" />
               </rules>
             </configuration>
           </execution>
@@ -74,6 +133,6 @@ Usage
 </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. 
+  Once you have configured your project, maven-enforcer will be able to throw a build error if current version follows semantic versioning principles. 
 
-  Some more detailed {{{./examples/checking-version.html}examples}} of the <<<checkVersionRule>>> rule.
+  Some more detailed {{{./examples/semantic-versioning-conformance.html}examples}} of the <<<requireSemanticVersioningConformance>>> rule.