enhance documentation, add CI with travis-ci, fixes #1

.travis.yml

@@ -0,0 +1,17 @@
+language: java
+
+script:
+  - mvn clean install
+
+install: /bin/true
+
+jdk:
+  - oraclejdk8
+
+branches:
+    except:
+        - gh-pages
+
+notifications:
+  email:
+    - matthieu@brouillard.fr

README.md

@@ -1,7 +1,92 @@
 # jgitver-maven-plugin
 
+This plugin allows to define the pom version of your project using the information from your git history. 
+It calculates the version, a little bit like `git describe` would do but in a more efficient way for maven projects:
+
+- new commits have upper version than previous commit (in the way maven/semver interpret versions)
+- version calculation is based on git tags
+- git lightweight tags allow for intermediate version controlling between releases
+    - allow to define what is the _next_ version pattern to use
+    - allow SNAPSHOTS
+- minimal setup via maven extension
+
+> DISCLAIMER: This plugin has been highly inspired by the work of [Brian Demers](https://github.com/bdemers) in his [maven-external-version](https://github.com/bdemers/maven-external-version/) plugin.
+
+Here is an illustration of the capabilities of the plugin
+
+![Example](src/doc/images/s7_linear_with_SNAPSHOT_tags_and_branch.gif?raw=true "Example")
+
+## Usage
+
+### pure extension
+
+Using the module as pure maven extension, allows a minimal setup inside your pom.
+
+```
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    ...
+    <version>0</version>    <!-- your project version becomes irrelevant -->
+    ...
+    <build>
+        <extensions>
+            <extension>
+                <groupId>fr.brouillard.oss</groupId>
+                <artifactId>jgitver-maven-plugin</artifactId>
+                <version>X.Y.Z</version>
+            </extension>
+        </extensions>
+    </build>
+</project>
+```
+
+Used like that _i.e._ as a pure extension, [jgitver](https://github.com/jgitver/jgitver) will be used with the following parameters:
+
+- __autoIncrementPatch__: `true` 
+- __useDistance__: `true`
+- __useGitCommitId__: `false` 
+- __nonQualifierBranches__: `master` 
+
+### plugin extension with configuration
+
+The plugin can also be defined as a plugin extension so that you have the possibility to define your own configuration, and thus bypass the default one:
+
+```
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    ...
+    <version>0</version>    <!-- your project version becomes irrelevant -->
+    ...
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>fr.brouillard.oss</groupId>
+                <artifactId>jgitver-maven-plugin</artifactId>
+                <version>X.Y.Z</version>
+                <extensions>true</extensions>
+                <configuration>
+                    <autoIncrementPatch>true/false</autoIncrementPatch>
+                    <useCommitDistance>true/false</useCommitDistance>
+                    <useGitCommitId>true/false</useGitCommitId>
+                    <gitCommitIdLength>integer</gitCommitIdLength>  <!-- between [8,40] -->
+                    <nonQualifierBranches>master</nonQualifierBranches> <!-- comma separated, example "master,integration" -->
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+```
+
 ## Example
 
+If you want to give it a try you can use the following script that will setup a demo project. 
+
+Then play around with it doing:
+
+- `mvn validate`
+- `mvn install`
+- `git checkout XXXX`
+
 ```
 rm -rf /d/demo-jgitver-maven-plugin
 mkdir /d/demo-jgitver-maven-plugin
@@ -11,18 +96,17 @@ cat > pom.xml << EOF
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>fr.brouillard.oss.demo</groupId>
-    <artifactId>demo-demo-jgitver-maven-plugin</artifactId>
+    <artifactId>demo-jgitver-maven-plugin</artifactId>
     <version>0</version>
     <packaging>pom</packaging>
     <build>
-        <plugins>
-            <plugin>
+        <extensions>
+            <extension>
                 <groupId>fr.brouillard.oss</groupId>
                 <artifactId>jgitver-maven-plugin</artifactId>
-                <version>0.0.1-SNAPSHOT</version>
-                <extensions>true</extensions>
-            </plugin>
-        </plugins>
+                <version>[0.0.2-SNAPSHOT,)</version>
+            </extension>
+        </extensions>
     </build>
 </project>
 EOF

pom.xml

@@ -20,7 +20,7 @@
 
     <groupId>fr.brouillard.oss</groupId>
     <artifactId>jgitver-maven-plugin</artifactId>
-    <version>0.0.1</version>
+    <version>0.0.2</version>
     <packaging>maven-plugin</packaging>
 
     <name>jgitver Maven Plugin</name>

src/main/java/fr/brouillard/oss/jgitver/GAV.java

@@ -120,4 +120,9 @@ public boolean equals(Object obj) {
         }
         return true;
     }
+
+    @Override
+    public String toString() {
+        return String.format("%s::%s::%s", groupId, artifactId, version);
+    }
 }

src/main/java/fr/brouillard/oss/jgitver/JGitverExtension.java

@@ -15,6 +15,8 @@
  */
 package fr.brouillard.oss.jgitver;
 
+import java.util.Optional;
+
 import org.apache.maven.AbstractMavenLifecycleParticipant;
 import org.apache.maven.MavenExecutionException;
 import org.apache.maven.execution.MavenSession;
@@ -39,9 +41,13 @@ public void afterProjectsRead(MavenSession session) throws MavenExecutionExcepti
         logger.info("jgitver-maven-plugin is about to change project version");
 
         MavenProject rootProject = session.getTopLevelProject();
+        GAV rootProjectInitialGAV = GAV.from(rootProject);      // SUPPRESS CHECKSTYLE AbbreviationAsWordInName
 
         String newVersion = calculateVersionForProject(rootProject);
         rootProject.setVersion(newVersion);
+        rootProject.getArtifact().setVersion(newVersion);
+
+        logger.info("    " + rootProjectInitialGAV.toString() + " -> " + newVersion);
     }
 
     private String calculateVersionForProject(MavenProject rootProject) throws MavenExecutionException {
@@ -51,8 +57,13 @@ private String calculateVersionForProject(MavenProject rootProject) throws Maven
             gvc = GitVersionCalculator.location(rootProject.getBasedir());
 
             Plugin plugin = rootProject.getPlugin("fr.brouillard.oss:jgitver-maven-plugin");
-            Xpp3Dom pluginConfigNode = (Xpp3Dom) plugin.getConfiguration();
-            JGitverPluginConfiguration pluginConfig = new JGitverPluginConfiguration(pluginConfigNode);
+
+            JGitverPluginConfiguration pluginConfig =
+                    new JGitverPluginConfiguration(
+                        Optional.ofNullable(plugin)
+                        .map(Plugin::getConfiguration)
+                        .map(Xpp3Dom.class::cast)
+                    );
 
             gvc.setAutoIncrementPatch(pluginConfig.autoIncrementPatch())
                 .setUseDistance(pluginConfig.useCommitDistance())

src/main/java/fr/brouillard/oss/jgitver/JGitverPluginConfiguration.java

@@ -19,41 +19,40 @@
 
 import org.codehaus.plexus.util.xml.Xpp3Dom;
 
-public class JGitverPluginConfiguration {
-    private Xpp3Dom pomPluginConfiguration;
+class JGitverPluginConfiguration {
+    private Optional<Xpp3Dom> pomPluginConfiguration;
 
-    public JGitverPluginConfiguration(Xpp3Dom pomPluginConfiguration) {
+    JGitverPluginConfiguration(Optional<Xpp3Dom> pomPluginConfiguration) {
         this.pomPluginConfiguration = pomPluginConfiguration;
     }
 
-    public boolean autoIncrementPatch() {
+    boolean autoIncrementPatch() {
         return booleanConfigChild("autoIncrementPatch", true);
     }
 
-    public boolean useCommitDistance() {
+    boolean useCommitDistance() {
         return booleanConfigChild("useCommitDistance", true);
     }
 
-    public boolean useGitCommitId() {
+    boolean useGitCommitId() {
         return booleanConfigChild("useGitCommitId", false);
     }
 
-    public int gitCommitIdLength() {
+    int gitCommitIdLength() {
         return intConfigChild("gitCommitIdLength", 8);
     }
 
-    public String nonQualifierBranches() {
-        return Optional.ofNullable(pomPluginConfiguration)
-                .map(node -> node.getChild("nonQualifierBranches")).map(Xpp3Dom::getValue).orElse("master");
+    String nonQualifierBranches() {
+        return pomPluginConfiguration.map(node -> node.getChild("nonQualifierBranches")).map(Xpp3Dom::getValue).orElse("master");
     }
 
     private boolean booleanConfigChild(String childName, boolean defaultValue) {
-        return Optional.ofNullable(pomPluginConfiguration)
-                .map(node -> node.getChild(childName)).map(Xpp3Dom::getValue).map(Boolean::valueOf).orElse(Boolean.valueOf(defaultValue));
+        return pomPluginConfiguration.map(node -> node.getChild(childName))
+                .map(Xpp3Dom::getValue).map(Boolean::valueOf).orElse(Boolean.valueOf(defaultValue));
     }
 
     private int intConfigChild(String childName, int defaultValue) {
-        return Optional.ofNullable(pomPluginConfiguration)
-                .map(node -> node.getChild(childName)).map(Xpp3Dom::getValue).map(Integer::parseInt).orElse(Integer.valueOf(defaultValue));
+        return pomPluginConfiguration.map(node -> node.getChild(childName))
+                .map(Xpp3Dom::getValue).map(Integer::parseInt).orElse(Integer.valueOf(defaultValue));
     }
 }