git-commit-id · TheSnoozer · Dec 24, 2018 · Dec 23, 2018 · Dec 23, 2018 · Dec 23, 2018
diff --git a/.travis.yml b/.travis.yml
@@ -6,6 +6,7 @@ stages:
   - checkstyle
   - test
   - Integration Test
+  - coveralls
 
 jdk:
   - oraclejdk11
@@ -40,6 +41,11 @@ matrix:
     jdk: oraclejdk8
     script: mvn clean verify -Pcheckstyle -Dmaven.test.skip=true -B
     env: CHECKSTYLE=8.2
+  - stage: coveralls
+    jdk: oraclejdk8
+    env:
+      secure: "nWocmaofFk759rTMC37hJ5qbLN9V7B5jwxuR15OhsHcE4WuijsatbEP6YY4Z6zomozKEaPYVA8rLbbpSY2B6JQffe4NV975647CZisp/WtJmkvsLEbio0mkJ2Jw11aHZ+o3OI17Kh/vxzVrjYusFuMok/AADT7bV9cBk/2l5u9I="
+    script: mvn clean test jacoco:report coveralls:report -Pcoveralls -DrepoToken=${COVERALLS_REPO_TOKEN} -B
 
 install:
   - if [[ -n "${CUSTOM_MVN_VERION}" ]]; then

diff --git a/README.md b/README.md
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,50 @@
+Frequently Asked Question (FAQ)
+=========
+
+Generated properties are not usable inside the pom / properties don't get exposed by the plugin
+-------------------------------
+Since version `2.1.4` there is a switch to control if you want the plugin to expose the generated properties to your pom as well.
+This switch is set to `false` by default to ensure that properties of reactor builds can't be overwritten by accident.
+Thus if you need this feature set `<injectAllReactorProjects>true</injectAllReactorProjects>` inside the plugin's config.
+
+If the properties are empty for some reason verify with the maven-antrun-plugin if they are correctly exposed.
+Example:
+```
+<plugin>
+  <artifactId>maven-antrun-plugin</artifactId>
+  <version>1.8</version>
+  <executions>
+    <execution>
+      <phase>package</phase>
+      <configuration>
+        <target>
+          <echo>Git-Infos: ${git.commit.id}</echo>
+        </target>
+      </configuration>
+      <goals>
+        <goal>run</goal>
+      </goals>
+    </execution>
+  </executions>
+</plugin>
+```
+
+If you are using the maven build with [Maven's Plugin Prefix Resolution](https://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html) (e.g. `mvn somePrefix:goal`) please note that this currently seems to be [not supported by maven](https://issues.apache.org/jira/browse/MNG-6260).
+Instead of using the Plugin Prefix Resolution add an execution tag that calls the desired goal of the plugin within a normal maven life cycle (e.g. `mvn clean package`).
+
+Generated properties are not being used in install and/or deploy
+-------------------------------
+If you try to use generated properties like ${git.commit.id} alongside with your artificat finalName you will soon notice that those properties are not being used in install and/or deploy. This specific behaviour is basically not intended / not supported by maven-install-plugin and/or maven-deploy-plugin (https://issues.apache.org/jira/browse/MINSTALL-1 / https://issues.apache.org/jira/browse/MDEPLOY-93). The naming format in the remote repo seems always $artifactId-$version-$classifier *by default* and thus any generated property will not end up inside the artifact being installed/deployed. If you for whatever reason still want to have something special you may want to [checkout a full workaround](https://github.com/git-commit-id/maven-git-commit-id-plugin/issues/256#issuecomment-321476196) that uses a specific configuration of `install-file` / `deploy-file`.
+
+As a general note also ensure to use `mvn clean deploy` instead of `mvn deploy:deploy` (or you run into  https://issues.apache.org/jira/browse/MNG-6260) and ensure to set `<injectAllReactorProjects>true</injectAllReactorProjects>` inside the plugin's config.
+
+How to contribute to the project
+-------------------------------
+In general pull requests and support for open issues is always welcome!
+If you open a pull request or want to help out in any way please keep in mind that we currently use `checkstyle` to ensure that the project somehow maintains a uniform code base. Fortunately the most common IDEs support the integration of `checkstyle` via plugins. On top of more or less native integration into modern development tools the `checkstyle` rules are currently also being verified by using the [maven-checkstyle-plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/) during the build. it should be worth to highlight that you are not required to install `checkstyle` inside your IDE. If you feel more comfortable running the checks via maven this would to the trick!
+The checkstyle rules for this project are currently residing in `src/test/resources/checks` and for some IDEs those rules need to be imported manually (unfortunately there is no better solution available for this yet). The current rule set is pretty much the same as the `google_checks.xml` with certain checks disabled (e.g. line length). If you choose to integrate `checkstyle` inside your IDE feel free to checkout some high level requirements to get started with checkstyle within your IDE:
+* eclipse -- for eclipse / STS you would need to install the `checkstyle plug-in` via `Help -> Eclipse Marketplace -> Search` after restarting eclipse it should pick-up the rules automatically. If this does not work out of the box checkout the [official integration guide](http://checkstyle.sourceforge.net/eclipse.html) or use google to trace down your error message.
+* IntelliJ IDEA -- for IntelliJ you would need to install the `CheckStyle-IDEA` via `File -> Settings -> Plugins -> Search`. After restarting IntelliJ you would need to import the `checkstyle` rules manually via `File -> Settings -> Checkstyle`. As checkstyle version you may choose `8.2` and then click on the plus-sign on the right. As description you may choose `maven-git-commit-id-plugin` and as local checkstyle file you may choose one of the checkstyle rule residing in `src/test/resources/checks`. Please note that the rule-file depend on the version you have selected in the previous step and thus it is essential to ensure that the version numbers match up. As next-step you unfortunately will be prompted to enter the **full directory** of the `checkstyle-suppressions.xml`-File. If this does not work out of the box checkout the [official integration guide](http://checkstyle.sourceforge.net/idea.html) or use google to trace down your error message.
+* Netbeans -- feel free to open a ticket and share your installation guide :-) You can also check out the [official integration guide](http://checkstyle.sourceforge.net/netbeans.html) or use google to get any addtional help.
+* Maven -- if you want to run `checkstyle` via maven you simply can execute `mvn clean verify -Pcheckstyle -Dmaven.test.skip=true -B`.
+
diff --git a/docs/git-describe.md b/docs/git-describe.md
@@ -0,0 +1,82 @@
+Git describe - short intro to an awesome command
+==================================================
+Git's [describe command](http://www.kernel.org/pub/software/scm/git/docs/git-describe.html) is the best way to really see "where" a commit is in the repositories "timeline". 
+
+In svn you could easily determine by looking at two revisions (their numbers) which one is "newer" (they look like that `r239`, `r240` ...). Since git is using SHA-1 checksums to identify commits, it's hard to tell which one is "newer" (or can you tell me? `b6a73ed` or `9597545`?). Using describe you can get a part of this back, and even more - you can know the "nearest" tag for a commit. And as tags are used for versioning most of the time that's super useful to track development progress.
+
+Let's get an example to explain git-describe on it:
+
+```
+* 2414721 - (HEAD, master) third addition (8 hours ago) <Konrad Malawski>
+| d37a598 - second line (8 hours ago) <Konrad Malawski>
+| 9597545 - (v1.0) initial commit (8 hours ago) <Konrad Malawski>
+```
+
+Running git-describe when you're on the HEAD here, will yield:
+
+```
+> git describe
+  v.1.0-2-b2414721
+```
+
+The format of a describe result is defined as:
+
+```
+v1.0-2-g2414721-DEV
+ ^   ^  ^       ^
+ |   |  |       \-- if a dirtyMarker was given, it will appear here if the repository is in "dirty" state
+ |   |  \---------- the "g" prefixed commit id. The prefix is compatible with what git-describe would return - weird, but true.
+ |   \------------- the number of commits away from the found tag. So "2414721" is 2 commits ahead of "v1.0", in this example.
+ \----------------- the "nearest" tag, to the mentioned commit.
+```
+
+Other outputs may look like:   
+
+* **v1.0** - if the repository is "on a tag" (though describe can be forced to print **v1.0.4-0-g2414721** instead if you want -- use the `full` config option),
+* **v1.0-DEV** - if the repository is "on a tag", but in "dirty" state. This dirty marker can, and will be included wherever possible,
+* **2414721** - a plain commit id hash if not tags were defined (of determined "near" this commit). 
+                *It does NOT include the "g" prefix, that is used in the "full" describe output format!*
+
+For more details (on when what output will be returned etc), see <code>man git-describe</code> (or here: [git-describe](http://www.kernel.org/pub/software/scm/git/docs/git-describe.html)). In general, you can assume it's a "best effort" approach, to give you as much info about the repo state as possible.
+
+**describe-short** is also provided, in case you want to display this property to non-techy users, which would panic on the sight of a hash (last part of the describe string) - this property is simply
+*the describe output, with the hash part stripped out*.
+
+git-describe and a small "gotcha" with tags
+-------------------------------------------
+You probably know that git has two kinds of tags:
+
+* **lightweight tags** - which are only a pointer to some object,
+* **annotated tags** - which are the same as a lightweight tag and contain additional information, such as a message linked with the tag.
+
+Knowing this, I now can tell you that when you run git-describe, it (by default) looks only for **annotated** tags.
+What this means in a real life scenario can be explained on such repository:
+
+```
+b6a73ed - (HEAD, master)
+d37a598 - (v1.0-fixed-stuff) - a lightweight tag (with no message)
+9597545 - (v1.0) - an annotated tag
+```
+
+When you run git describe without any options (note that git-commit-id is "acting like" plain git, so all behaviour is as described here, unless you configure it to act otherwise (using the `<tags>true</tags>` option)):
+
+```
+> git describe
+  annotated-tag-2-gb6a73ed     # the nearest "annotated" tag is found
+```
+
+So it did not find the lightweight tag! Do not panic, there's a flag to help with that:
+
+```
+> git describe --tags
+  lightweight-tag-1-gb6a73ed   # the nearest tag (including lightweights) is found
+```
+
+Using only annotated tags to mark builds may be useful if you're using tags to help yourself with annotating
+things like "i'll get back to that" etc - you don't need such tags to be exposed. But if you want lightweight
+tags to be included in the search, enable this option.
+
+<blockquote>
+TIP: If you're using maven's `release:prepare` and `release:perform` it's using <em>annotated</em> tags.
+</blockquote>
+
diff --git a/docs/use-cases.md b/docs/use-cases.md
@@ -0,0 +1,40 @@
+Use cases
+=========
+Which version had the bug? Is that deployed already?
+----------------------------------------------------
+If you develop your maven project inside an git repository you may want to know exactly what changeset is currently deployed. Why is this useful? 
+
+I worked in a team where the testers would come up to the development team and say: "hey, feature X is still broken!", to which a dev would reply "But I fixed it this morning!". Then they'd investigate a bit, only to see that the next version which would be deployed very soon included the needed fix, yet the developer already marked it as "ready for testing".
+
+The fix here is obvious: include the version you fixed some bug in the issue comment where you mark it as "ready for testing". You can either do this via smart tooling (recommended), or just manually put in a comment like "fixed in v1.4.3-324-g45xhbghv" (that's a git-describe output - explained in detail bellow), so the testing crew knows it doesn't make sense to pickup testing of this feature until at least "324" (or greater) is included in the version output (it means "number of commits away from the mentioned tag" - readup on git-describe to understand how it works).
+
+Make your distributed deployment aware of versions
+---------------------------------------------
+Let's say you have a large distributed deployment where the servers need to talk to each other using some protocol. You have them configured to keep talking with servers of the same major + minor version number. So a server running "3.3.233" may still talk with one that has "3.3.120" - the protocol is guaranteed to not have changed in these versions.
+
+And now imagine that you need to deploy a drastic API change - so the new version of the servers will be "3.4.0". You can't afford to bring the system down for the deployment. But as the servers are configured to only talk with compatible versions - you're in luck. You can start the deployment process and each node, one by one will be replaced with the new version - the old servers simply stop communicating with them, and the new versions start talking with each other until only the "new" nodes are left.
+
+Using this plugin, you can easily expose the information needed - based on git tags for example. 
+One might say that this is usually accomplished by using `${project.version}` and I generally would agree, but maybe tags would fit your use case better than a plain version. :-)
+
+Validate if properties are set as expected
+---------------------------------------------
+Since version **2.2.2** the maven-git-commit-id-plugin comes equipped with an additional validation utility which can be used to verify if your project properties are set as you would like to have them set.
+The validation can be used for *any* property that is visible inside the pom.xml and therefore can be used for a various amount of different use cases.
+In order to understand the ideology and intention here are some pretty useful ideas you could achieve by using the validation:
+* validate if the version of your project does not end with SNAPSHOT
+* validate if you are currently on a tag
+* ensure that your repository is not dirty
+* may other's :-)
+
+With the current version of the validation the user can decide if the build should fail if *at least one* of the defined criteria do not match with the desired values.
+
+For flexibility and due to the fact that this validation has a different scope than the maven-git-commit-id-plugin this validation needs to be configured as additional execution inside the configuration of the pom.xml.
+Once configured, the validation is executed during the verification-phase. However since the validation is done in a separate execution the phase can easily be changed by adding the desired phase to the execution configuration.
+
+Note that this feature needs to be enabled properly, before it can be used. Checkout the `Validation Usage Example` in the [using the plugin](using-the-plugin.md) guide to find out more.
+
+Other
+-----
+If you have a nice use case to share, please do fork this file and file a pull request with your story :-)
+