Skip to content

An opinionated plugin that provides Semantic Versioning for Gradle projects that use Gitflow.

License

Notifications You must be signed in to change notification settings

uw-it-edm/gradle-gitflow

 
 

Repository files navigation

gradle-gitflow

Download Documentation License Build Status Dependency Status Semantic Versioning Gitflow

An opinionated plugin that provides Semantic Versioning for Gradle projects that use Gitflow.

This plugin is heavily inspired by the gradle-git plugin.

Important
It intentionally provides no Gradle tasks and interacts with Git just for inferring the version of the project.

This inferred version is set as the project version of the Gradle project to which it is applied.

The rules applied when inferring the version are that simple:

  • If the current commit is tagged this tag is used as a version — regardless of the current branch

    • this would usually be the normal version (major.minor.patch)

  • Otherwise the version contains

    • the normal version (major.minor.patch) extracted from the next reachable tag in the history

      • if the current commit is on a pre-release branch, the normal version is extracted from the name of this branch

    • a pre-release identifier indicating the current branch

    • a pre-release identifier indicating the number of commits since the last tag

    • a build metadata identifier indicating the SHA of the current commit

    • a build metadata identifier indicating if the repository is dirty

The inferred versions consist of the following components:

1.2.3-dev+dirty-SNAPSHOT
| | |  |  |     |
| | |  |  |     |
| | |  |  |     |
| | |  |  |     |
| | |  |  |     |
| | |  |  |     added if you are not on a RELEASE branch
| | |  |  |
| | |  |  indicates if the repository is dirty
| | |  |
| | |  denotes the current branch
| | |
| | patch version
| |
| minor version
|
major version

The following table shows the mapping between Gitflow branches and the corresponding pre-release identifiers that indicate these branches.

Note
If you use a Gitflow plugin for Git, gradle-gitflow uses the branch names and prefixes of your Gitflow configuration section in .git/config. If you do not use such a plugin, you will either have to stick to the default names in the table below or add Gitflow configuration sections to .git/config as described in Gitflow plugins for Git.
Gitflow branch Default name in Gitflow plugins Pre-release identifier Notes

production release

master

(empty string)

development

develop

dev

feature

feature/foo

feature.foo

next release / pre-release

release/1.2.3

pre

The normal version (major.minor.patch) is extracted from the branch name

hotfix

hotfix/foo

fix.foo

support

support/foo

support.foo

Note
In case the current head is a detached head the pre-release identifier is detached.

Include the following in the project on which you want to apply the plugin:

buildscript {
  repositories {
    jcenter()
  }

  dependencies {
    classpath 'edu.uw.concert:gradle-gitflow:0.3.0'
  }
}

apply plugin: 'edu.uw.concert.gitflow'
Note
The latest build of the current development version can always be obtained from here.

The plugin registers an extension object named gitflow that is the entry point to the configuration. It also provides a DSL for keyword-based configuration, but configuration via properties is also possible. The following example shows all configuration options:

gitflow {
  // Use a different Git repository
  repositoryRoot 'foo/bar' // defaults to project.projectDir

  // Pre-release identifiers based on Gitflow branches
  preReleaseIds {
    release 'foo'      // defaults to ''
    develop 'foo'      // defaults to 'dev'
    preRelease 'foo'   // defaults to 'pre'
    detachedHead 'foo' // defaults to 'detached'

    // The following ones are used as prefixes
    feature 'foo' // defaults to 'feature'
    hotfix 'foo'  // defaults to 'fix'
    support 'foo' // defaults to 'support'
  }

  // Build metadata identifiers that are used as static text
  buildMetadataIds {
    sha 'foo'   // Defaults to 'sha'
    dirty 'foo' // Defaults to 'dirty'
  }
}

This plugin supports the following Gitflow plugins for Git:

If you do not use one of the mentioned plugins and differ from the default names mentioned in Mapping between Gitflow branches and pre-release identifiers, you will have to manually set the branch names and prefixes of the Gitflow branches and prefixes in .git/config like these plugins would do. This is the only way for gradle-gitflow to pick up this configuration.

The following example shows the default configuration of the above plugins:

[gitflow "branch"]
	master  = master
	develop = develop
[gitflow "prefix"]
	feature    = feature/
	release    = release/
	hotfix     = hotfix/
	support    = support/
	versiontag =
Warning
Keep in mind that most CI servers simply clone your repository after being called by a commit hook when you push your code. Therefore you will have to take care in your CI configuration that .git/config contains the Gitflow configuration sections that gradle-gitflow needs if you do not use the default names mentioned in Mapping between Gitflow branches and pre-release identifiers.

The following additional functionality is provided by the version object that this plugin provides. You can have a look at the Groovydoc documentation for further information.

The type of the inferred version is derived from the current branch and corresponds to the branches mentioned in Mapping between Gitflow branches and pre-release identifiers. This can be used in your buildscripts for distinguishing between development and production builds, e.g. for deploying to staging and production as seen in the following example.

import static edu.uw.concert.gradle.gitflow.version.VersionType.*

task deploy << {
  if (version.type == DEVELOP) {
    // Deploy to staging...
  } else if (version.type == RELEASE) {
    // Deploy to production...
  }
}
Tip
For additional version types see the enum VersionType in the Groovydoc documentation.

About

An opinionated plugin that provides Semantic Versioning for Gradle projects that use Gitflow.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Groovy 100.0%