Merge pull request #1499 from davidvc/master

Clarify Maven plugin documentation

provider/maven/README.md

@@ -1,16 +1,19 @@
-Maven plugin to verify a provider
-=================================
+Pact Maven plugin 
+=================
 
-Maven plugin for verifying pacts against a provider.
+This is a Maven plugin for verifying pacts against a running provider, publishing pacts generated by consumer tests, 
+and checking if you can deploy.  The sections below provide details on each of these goals.
 
 <hr/>
 
 **![stop](https://raw.githubusercontent.com/pact-foundation/pact-jvm/master/provider/maven/stop.jpg) If you are running your tests with the JUnit runners, you do not need this plugin**
 
-**This plugin is for verifying a running provider. For verifying your provider using unit tests, refer to the [JUnit 4](../junit) or [JUnit 5](../junit5) docs.**
+**This plugin is used to verify a running provider. If you want to verify your provider using unit tests, refer to the [JUnit 4](../junit) or [JUnit 5](../junit5) docs.**
 
 <hr/> 
 
+# Verifying a Provider
+
 The Maven plugin provides a `verify` goal which will verify all configured pacts against your provider.
 
 ## To Use It
@@ -654,13 +657,13 @@ By default, the test classpath is scanned for annotated methods. You can overrid
 
 # Publishing pact files to a pact broker
 
-**NOTE**: There is a pact CLI that can be used to publish pacts. See https://github.com/pact-foundation/pact-ruby-cli.
+**NOTE**: There is also a pact CLI that can be used to publish pacts. See https://github.com/pact-foundation/pact-ruby-cli.
 
-The pact maven plugin provides a `publish` mojo that can publish all pact files in a directory
-to a pact broker. To use it, you need to add a publish configuration to the POM that defines the
-directory where the pact files are and the URL to the pact broker.
+The pact maven plugin provides a `publish` goal that can publish all pact files in a directory
+to a pact broker. To use it, at a minimum you need to configure the plugin to specify the directory 
+of the pact files and the URL to the pact broker.  
 
-For example:
+Here is an example configuration:
 
 ```xml
 <plugin>
@@ -670,20 +673,25 @@ For example:
     <configuration>
       <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts -->
       <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl>
-      <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} -->
+      <projectVersion>${git.shorthash}</projectVersion> <!-- Defaults to ${project.version}, or you can generate your own version from git -->
       <trimSnapshot>true</trimSnapshot> <!-- Defaults to false -->
-      <skipPactPublish>false</skipPactPublish> <!-- Defaults to false -->
+      <skipPactPublish>${pact.skipPublish}</skipPactPublish> <!-- Defaults to false -->
     </configuration>
 </plugin>
 ```
 You can now execute `mvn pact:publish` to publish the pact files.
 
-_NOTE:_ The pact broker requires a version for all published pacts. The `publish` task will use the version of the
-project by default, but can be overwritten with the `projectVersion` property. Make sure you have set one otherwise the broker will reject the pact files.
+_NOTE:_ The pact broker requires a version for the consumer for all published pacts. The plugin will use the maven
+`project.version` property by default, but you can override this using the `projectVersion` configuration setting.  For
+example, you may want to use the git hash as the version identifier.
 
 _NOTE_: By default, the pact broker has issues parsing `SNAPSHOT` versions.  You can configure the publisher to 
 automatically remove `-SNAPSHOT` from your version number by setting `trimSnapshot` to true. This setting does not modify non-snapshot versions.
 
+It may be that in some situations you want to disable pact publication. You can use the `skipPactPublish` setting
+to disable publication. For example, you can have this setting be controlled by a system property that you set to false
+in some environments. 
+
 You can set any tags that the pacts should be published with by setting the `tags` list property. A common use of this
 is setting the tag to the current source control branch. This supports using pact with feature branches.
 
@@ -695,15 +703,14 @@ is setting the tag to the current source control branch. This supports using pac
     <configuration>
       <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts -->
       <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl>
-      <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} -->
       <tags>
-        <tag>feature/feature_name</tag>
+        <tag>${git.branch}</tag>
       </tags>
     </configuration>
 </plugin>
 ```
 
-You can also specify the tags using the `pact.consumer.tags` Java system property [version 4.0.7+].
+_NOTE:_ You can also specify the tags using the `pact.consumer.tags` Java system property [version 4.0.7+].
 
 ## Publishing to an authenticated pact broker