Merge pull request #94 from egineering-llc/release/2.0.0

Release/2.0.0

.travis.yml

@@ -3,8 +3,7 @@ language: java
 script: mvn verify
 
 jdk:
- - openjdk7
- - oraclejdk8
+ - openjdk8
 
 cache:
   directories:
@@ -14,3 +13,6 @@ notifications:
   email:
     recipients:
      - [email protected]
+
+after_success:
+  - mvn jacoco:report coveralls:report

README.md

@@ -1,4 +1,4 @@
-# gitflow-helper-maven-plugin [![Build Status](https://travis-ci.org/egineering-llc/gitflow-helper-maven-plugin.svg?branch=master)](https://travis-ci.org/egineering-llc/gitflow-helper-maven-plugin)
+# gitflow-helper-maven-plugin [![Build Status](https://travis-ci.org/egineering-llc/gitflow-helper-maven-plugin.svg?branch=master)](https://travis-ci.org/egineering-llc/gitflow-helper-maven-plugin) [![Coverage Status](https://coveralls.io/repos/github/egineering-llc/gitflow-helper-maven-plugin/badge.svg)](https://coveralls.io/github/egineering-llc/gitflow-helper-maven-plugin)
 
 A build extension and plugin that helps Maven play nicely with gitflow projects, CI servers and local development.
 
@@ -10,6 +10,7 @@ It does so by:
     * SCM tagging builds for master and support branches. You can use the project SCM definition, or if you omit it, you can resolve the CI server's repository connection information. (Zero Maven scm configuration necessary)
     * Promoting existing tested (staged) artifacts for release, rather than re-building the artifacts. Eliminates the risk of accidental master merges or commits resulting in untested code being released, and provides digest hash traceability for the history of artifacts.
     * Enabling the decoupling of repository deployment and execution environment delivery based on the current git branch.
+    * Allowing for long-running non-release branches to be deployed to snapshots, automatically reversioning the artifacts based off the branch name.
  * Automated deployment, promotion, and delivery of projects without the [maven-release-plugin](http://maven.apache.org/maven-release/maven-release-plugin/) or some other [*almost there* solution](https://axelfontaine.com/blog/final-nail.html).
  * Customizing maven project and system properties based upon the current branch being built. This allows test cases to target different execution environments without changing the artifact results.
  * Enabling automatic purging and resolving (force update) of 'release' and 'hotfix' release versioned dependencies resolved from the 'stage' repository.
@@ -24,6 +25,7 @@ This plugin solves a few specific issues common in consolidated Hudson/Jenkins C
  4. Set arbitrary project properties based upon the type of GIT branch being built. 
  5. Reliably tag deploy builds from the master and support branches
  6. Enable split 'deploy' vs. 'deliver' maven CI job configuration, without rebuilding artifacts for the 'deliver' phase.
+ 7. Allow for deployment of long-running feature branches to repositories without having to mangle the version in the pom.xml.
 
 In addition to supporting these goals for the project, this plugin does it in a manner that tries to be as effortless (yet configurable) as possible.
 If you use non-standard gitflow branch names (emer instead of hotfix), this plugin supports that. If you don't want to do version enforcement, this plugin supports that. 
@@ -107,14 +109,16 @@ All of the solutions to these issues are implemented independently in different
                     <releaseDeploymentRepository>localnexus-releases</releaseDeploymentRepository>
                     <stageDeploymentRepository>localnexus-stage</stageDeploymentRepository>
                     <snapshotDeploymentRepository>localnexus-snapshots</snapshotDeploymentRepository>
+                    <!-- Allow branches starting with feature/poc to be published as automagically versioned branch-name-SNAPSHOT artifacts -->
+                    <otherDeploymentBranchPattern>(origin/)feature/poc/.*</otherDeploymentBranchPattern>
                 </configuration>
                 <executions>
                     <execution>
                         <goals>
                             <goal>enforce-versions</goal>
+                            <goal>set-properties</goal>
                             <goal>retarget-deploy</goal>
                             <goal>update-stage-dependencies</goal>
-                            <goal>set-properties</goal>
                             <goal>tag-master</goal>
                             <goal>promote-master</goal>
                         </goals>
@@ -124,7 +128,6 @@ All of the solutions to these issues are implemented independently in different
                             <hotfixBranchPropertyFile>foo/bar/emer.props</hotfixBranchPropertyFile>
                             <releaseBranchPropertyFile>foo/bar/test.props</releaseBranchPropertyFile>
                             <developmentBranchPropertyFile>foo/bar/dev.props</developmentBranchPropertyFile>
-                            <featureOrBugfixBranchPropertyFile>foo/bar/feat.props</featureOrBugfixBranchPropertyFile>
                             <otherBranchPropertyFile>foo/bar/ci.props</otherBranchPropertyFile>
                             <undefinedBranchPropertyFile>foo/bar/local.props</undefinedBranchPropertyFile>
                         </configuration>
@@ -144,9 +147,9 @@ One common stumbling block for teams adjusting to gitflow with Maven projects is
 In practice, the Maven versions should:
 
  * Be synchronized with release branch and hotfix branch names.
- * Never be -SNAPSHOT in the master, support, release, or hotfix branches. Also, no -SNAPSHOT parent or (plugin) dependencies are allowed. (This condition may be disabled by setting `enforceNonSnapshots` = `false`.)
- * Always be -SNAPSHOT in the feature and develop branches.
- * Be irrelevant if there's no git branch resolvable from your environment.
+ * Never be -SNAPSHOT in the master, support, release, or hotfix branches. Also, no -SNAPSHOT parent or (plugin) dependencies are allowed.
+ * Always be -SNAPSHOT in the develop branch.
+ * Be irrelevant if there's no git branch resolvable from your environment or working in a branch which is not deployed to remote repositories.
 
 The `enforce-versions` goal asserts these semantics when it can resolve the `gitBranchExpression`.
 
@@ -166,9 +169,21 @@ The following properties change the behavior of this goal:
 | supportBranchPattern | (origin/)?support/(.*) | No | Regex. When matches, signals a support branch (long term master-equivalent for older release) being built. Last subgroup, if present, must be start of the Maven project version. |
 | releaseBranchPattern | (origin/)?release/(.*) | No | Regex. When matched, signals a release branch being built. Last subgroup, if present, must match the Maven project version. |
 | hotfixBranchPattern  | (origin/)?hotfix/(.*) | No | Regex. When matched, signals a hotfix branch is being built. Last subgroup, if present, must match the Maven project version. |
-| featureOrBugfixBranchPattern | (origin/)?(?:feature&#124;bugfix)/(.*) | Yes | Regex. When matched, signals a feature or bugfix branch is being built. |
 | developmentBranchPattern | (origin/)?develop | Yes | Regex. When matched, signals a development branch is being built. Note the lack of a subgroup. |
 
+## Goal: `set-properties` (Dynamically Set Maven Project / System Properties)
+
+Some situations with automated testing (and integration testing in particular) demand changing configuration properties 
+based upon the branch type being built. This is a common necessity when configuring automated DB refactorings as part of
+a build, or needing to setup / configure datasources for automated tests to run against.
+
+The `set-properties` goal allows for setting project (or system) properties, dynamically based on the detected git
+branch being built. Properties can be specified as a Properties collection in plugin configuration, or can be loaded
+from a property file during the build. Both property key names and property values will have placeholders resolved.
+
+Multiple executions can be configured, and each execution can target different scopes (system or project), and can load
+properties from files with an assigned keyPrefix, letting you name-space properties from execution ids.
+
 
 ## Goal: `retarget-deploy` (Branch Specific Deploy Targets & Staging)
 
@@ -185,11 +200,10 @@ plugins in the build process (deploy, site-deploy, etc.) will use the repositori
 | Property | Default Value | Description | 
 | -------- | ------------- | ----------- |
 | gitBranchExpression  | current git branch resolved from SCM or ${env.GIT_BRANCH} | Maven property expression to resolve in order to determine the current git branch |
-| deploySnapshotTypeBranches  | `false` | When `true`, feature branches will also be deployed to the snapshots repository. |
 | releaseDeploymentRepository | n/a | The repository to use for releases. (Builds with a GIT_BRANCH matching `masterBranchPattern` or `supportBranchPattern`) |
 | stageDeploymentRepository | n/a | The repository to use for staging. (Builds with a GIT_BRANCH matching `releaseBranchPattern` or `hotfixBranchPattern`) | 
 | snapshotDeploymentRepository | n/a | The repository to use for snapshots. (Builds matching `developmentBranchPattern`) |
-
+| otherDeploymentBranchPattern | n/a | Regex. When matched, the branch name is normalized and any artifacts produced by the build will include the normalized branch name and -SNAPSHOT. Deployment will target the snapshot repository |
 
 **The repository properties should follow the following format**, `id::layout::url::uniqueVersion`.
 
@@ -238,20 +252,15 @@ Can be replaced with the following plugin configuration, which also introduces t
         ...
     </build>
 
+### Deploying non-release (OTHER) type branches as -SNAPSHOT releases.
 
-## Goal: `set-properties` (Dynamically Set Maven Project / System Properties)
-
-Some situations with automated testing (and integration testing in particular) demand changing configuration properties 
-based upon the branch type being built. This is a common necessity when configuring automated DB refactorings as part of
-a build, or needing to setup / configure datasources for automated tests to run against.
-
-The `set-properties` goal allows for setting project (or system) properties, dynamically based on the detected git
-branch being built. Properties can be specified as a Properties collection in plugin configuration, or can be loaded
-from a property file during the build. Both property key names and property values will have placeholders resolved.
-
-Multiple executions can be configured, and each execution can target different scopes (system or project), and can load
-properties from files with an assigned keyPrefix, letting you name-space properties from execution ids.
-
+In addition to setting up repository targets for release branches, the `retarget-depoy` branch can deploy other branches
+matching the `otherDeploymentBranchPattern` as -SNAPSHOT artifacts which include the branch name as build metadata.
+This is loosely based on the [semVer](https://semver.org) semantic version scheme, in that the plugin will reversion any
+artifacts to be produced with `+feature-branch-name-normalized-SNAPSHOT` where any characters not in `[0-9A-Za-z-.]` will
+be replaced with `-`. Artifact versions for feature branches will _always_ be -SNAPSHOT, and will _always_ target the 
+Snapshots repository. The intent for this configuration setting is to provide a way for long-running branches (matching 
+a naming convention you define) can be published to a SNAPSHOT repo for use by other projects.
 
 ## Goal: `update-stage-dependencies` (Force update of dependency staged Releases)
 
@@ -339,8 +348,8 @@ The following table describes the git branch expression -> repository used for r
 | supportBranchPattern  | release    |
 | releaseBranchPattern  | stage      |
 | hotfixBranchPattern   | stage      |
-| featureOrBugfixBranchPattern | snapshots | 
 | developmentBranchPattern | snapshots | 
+| otherBranchesToDeploy | snapshots | 
 | All Others            | local      |
 
 As an example, assume you have two CI jobs. 
@@ -361,15 +370,40 @@ it's building. The attach-deploy will 'clean' the maven project, then download t
 that the first build deployed into. Once they're attached to the project, the `jboss-as:deploy-only` goal will deliver
 the artifacts built by the first job into a jboss application server.
 
+# Additional Notes
+## How Git branch name resolution works
+1. If the `<scm>` sections of the pom points to a git repository,  `git symbolic-ref HEAD` to is used to check the local branch name.
+2. If the `symbolic-ref` fails then it's likely due to a detached HEAD.
+   This is typical of CI servers like Jenkins, where the commit hash that was just pushed is pulled.
+   This can also be done as a consequene of attempting to rebuild from a tag, without branching, or in some 
+   workflows where code reviews are done without branches.   
+
+   In the case of a detached HEAD the plugin will:
+    * Resolve the HEAD to a commit using `git rev-parse HEAD`.
+    * `git show-ref` to resolve which (local/remote) branches point to the commit.
+    * If the detached HEAD commit resolves to a single branch type, it uses that branch name.
+3. If the first two methods fail, the plugin attempts to resolve `${env.GIT_BRANCH}`.
+
+## To Debug the plugin (replicating a test-case but without being run from jUnit)
+You can 'bootstrap' the plugin into your local repository and get the test project stubbed by running:
+`mvn -Dmaven.test.skip=true install` 
+
+Then, change directories:
+`cd target/test-classes/project-stub`
+
+From there, you'll need to supply the required environment variables or commandline arguments to `mvnDebug`:
+```
+export GIT_BRANCH=origin/feature/mybranch-foo-bar
+mvnDebug -Dstub.project.version=5.0.0-SNAPSHOT -DotherBranchDeploy=semver -DallowGitflowPluginSnapshot=true  deploy
+```
+You can then connect a remote debugger and step through the plugin code.
 
-# Resolving the Git branch name
-As stated before, the plugin determines what to do by resolving the Git branch name.
+## Building with IntelliJ IDEA notes
+### To Debug Test Code:
+Configure the Maven commandline to include
+`-DforkMode=never` You will likely get warnings when you run maven with this argument.
 
- * The first try is a `git symbolic-ref HEAD` to check the local branch name. If it's found, that's the branch name that's used.
- * If the `symbolic-ref` fails then it's probably due to a detached HEAD. This typically happens on Jenkins, when it simply checks out the commit hash that was just pushed.
-   Or, it's because of a developer doing a `git checkout origin/feature/x`, e.g. when doing a code review and no local branch is required.
-   In such a case:
-    * The plugin will first resolve the HEAD to a commit using `git rev-parse HEAD`.
-    * Next, it will do a `git show-ref` to check which (local/remote) branches point to the commit.
-    * If it can resolve the commit to a single branch type (e.g. develop or master) then that's the branch name that's used.
- * If all of the above fails, `${env.GIT_BRANCH}` is tried.
+### To inspect code-coverage results from Integration Tests:
+* Select the **Analyze** -> **Show Coverage Data** menu.
+* In the dialog that appears, click the **+** in the upper left corner to `Add (Insert)`, and browse to `target/jacoco.exec`.
+* Selecting that file will show coverage data in the code editor.