AutoRelease (Jervis 1.6 API)

net.gleske.jervis.tools.AutoRelease

This utility class provides automatic release methods such as pattern matching and version bumping if given existing releases.

Sample usage

To run this example, clone Jervis and execute ./gradlew console to bring up a Groovy Console with the classpath set up.

import static net.gleske.jervis.tools.AutoRelease.getScriptFromTemplate
import static net.gleske.jervis.tools.AutoRelease.getNextRelease
import static net.gleske.jervis.tools.AutoRelease.getNextSemanticRelease
import static net.gleske.jervis.tools.AutoRelease.isMatched

String template = '''
Say hello to the ${type}: <% print kinds.join(', ') %><% kinds.each { String kind -> %>
  Hello ${kind}!<% } %>
'''.trim()
println "Show a string built from a simple Groovy template:"
println getScriptFromTemplate(template, [type: 'animals', kinds: ['dog', 'cat', 'snake']])
println getScriptFromTemplate(template, [type: 'people', kinds: ['sam', 'kristie', 'tammy']])
println()

String date = new Date().format('YYMMdd')
List git_tags = ['v1.1', 'v1.2', '1.1.2-1']

println 'the first release for a date-based version comparing already released git tags:'
println getNextRelease(date, git_tags)
println()

println 'the 3rd release for a version whose git tags start with the prefix "v"; hotfix releases keep a "." as the separator:'
println getNextRelease('1.0', git_tags, '.', 'v')
println()

println 'get the next semantic versioning hotfix release when a hotfix for 1.1.2 has already been released as git tags:'
println getNextSemanticRelease('1.1.2', git_tags)
println()

println('='*80)
println 'check some version numbers to see if they are a valid semantic versioning format'
println()
['1.0', '1.0.1-3', '1.2.1', '1.2.1-beta', '1.0.0-rc', '1.0-beta'].each { String version ->
    println "${version} version matches semantic versioning?"
    println isMatched('/([0-9]+\\.){2}[0-9]+(-.*)?$/', version)
    println()
}
println('='*80)

Methods Summary

Methods
Type Params	Return Type	Name and description
	`static String`	`getNextRelease(String version, List<String> git_tags, String hotfix_seperator = '.', String prefix = '')` Gets a bumped version with a more loosely formed format.
	`static String`	`getNextSemanticRelease(String version, List<String> git_tags, String prefix = '')` Provides automatically getting the next version for semantic versioning.
	`static String`	`getScriptFromTemplate(String script, Map variables)` This method is for applying variables to a groovy template.
	`static boolean`	`isMatched(String expression, String value)` Matches a string against an expression.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

Method Detail

static String getNextRelease(String version, List<String> git_tags, String hotfix_seperator = '.', String prefix = '')

Gets a bumped version with a more loosely formed format. This automatic releasing method is similar to semantic versioning but it is not as strict. Passed in version numbers can be anything. For more strict semantic versioning see getNextSemanticRelease.

For Java, Python, and other languages

-SNAPSHOT is automatically stripped from version as part of getting the next semantic version release. The following table shows what next version bump will be if given a version, a list of git_tags, and sometimes a prefix for known Git tags.

Current version	Git tags	Hotfix separator	Tag prefix	Next release returned
`1.0-SNAPSHOT`	`1.1`, `1.2`	`.` (period)	none	`1.3`
`1.1.5`	`1.1.6`, `1.1.5.1`, `1.1.5.2`	`.` (period)	none	`1.1.5.3`
`2.1-SNAPSHOT`	`client-2.1.1`, `client-2.1.2`	`.` (period)	`client-`	`client-2.1.3`
`1.3`	`v1.1.1`, `v1.2.1`, `v1.3.1`, `v1.3.2`, `v1.3.3`	`.` (period)	`v`	`v1.3.4`
`1.3.0`	`v1.1.1`, `v1.2.1`, `v1.3.1`, `v1.3.2`, `v1.3.3`	`.` (period)	`v`	`v1.3.4`
`1.0`	`v1.1`, `v1.2`, `v1.3`, `v1.3.2`, `v1.3.3`	`.` (period)	`v`	`v1.4`
`20200101`	`20200101-1`, `20200101-2`	`-` (hyphen)	none	`20200101-3`

Please note that if the last digit of the version number is .0 then it is treated similarly as -SNAPSHOT and trimmed off. e.g. 1.0.0 will bump to 1.0.X.

Parameters:: version - A version number pulled from the current commit of a project (e.g. pom.xml version) which will be used to determine the next release.; git_tags - A list of tags pulled from Git. These will be evaluated against the version and used to determined what the next highest version should be. This can be a list of all Git tags. This method will automatically filter for appropraite tags based on the given version. If a prefix is defined then tags will besearched for the version prepended by the prefix.; hotfix_separator - The separator used when hotfixes are applied past the first 3 sets of decimal numbers. By default, hotfix_separator is a period (.). A hotfix release would be something like 1.0.3.1. If you customize the hotfix_separator to be a different character such as a hyphen (-), then a hotfix release would be like 1.0.3-1.; prefix - A prefix which will be automatically stripped during version bumping. However, the prefix will automatically be prependend to the next release. prefix is optional and is empty by default.

Returns:: The next semantic release for the given version when a list of known git_tags is provided. If a prefix was provided then the next semantic release will be prepended with the prefix. That means if you're setting the next version and you don't want the prefix you'll have to strip it from the returned result.

static String getNextSemanticRelease(String version, List<String> git_tags, String prefix = '')

Provides automatically getting the next version for semantic versioning. This is utility function can make it easier to provided automated continuous release of projects which follow semantic versioning.

For NodeJS and strict semantic versioning

NodeJS follows a very strict version format for semantic versioning. NodeJS only allows the following two formats for version: W.X.Y and W.X.Y-Z where W, X, and Y are integers. Z can be anything. In the case of this method, it treats Z as a hotfix number which needs to be bumped.

Current version	Git tags	Tag prefix	Next release returned
`0.1.0`	`0.1.1`, `0.1.2`	none	`0.1.3`
`1.1.5`	`1.1.6`, `1.1.5-1`, `1.1.5-2`	none	`1.1.5-3`
`2.1.0`	`client-2.1.1`, `client-2.1.2`	`client-`	`client-2.1.3`
`1.3.0`	`v1.1.1`, `v1.2.1`, `v1.3.1`, `v1.3.2`, `v1.3.3`	`v`	`v1.3.4`
`1.3.2`	`v1.1.1`, `v1.2.1`, `v1.3.1`, `v1.3.2`, `v1.3.3`	`v`	`v1.3.2-1`
`1.3.2`	`v1.1.1`, `v1.2.1`, `v1.3.1`, `v1.3.2`, `v1.3.3`, `v1.3.2-1`, `v1.3.2-2`	`v`	`v1.3.2-3`
`1.3.2-1`	`v1.1.1`, `v1.2.1`, `v1.3.1`, `v1.3.2`, `v1.3.3`, `v1.3.2-1`, `v1.3.2-2`	`v`	`v1.3.2-1-1`
`1.0.0-rc`	`v0.10.3`, `v1.0.0-rc-1`	`v`	`v1.0.0-rc-2`
`1.1.0-beta`	`v0.10.3`, `v1.0.0-rc-1`	`v`	`v1.1.0-beta-1`
`1.1.0-beta`	`1.1.0-beta-1`, `1.1.0-beta-2`, `1.1.0-beta-3`	none	`1.1.0-beta-4`

Parameters:: version - A version number pulled from the current commit of a project (e.g. pom.xml version) which will be used to determine the next release.; git_tags - A list of tags pulled from Git. These will be evaluated against the version and used to determined what the next highest version should be. This can be a list of all Git tags. This method will automatically filter for appropraite tags based on the given version.; prefix - A prefix which will be automatically stripped during version bumping. However, the prefix will automatically be prependend to the next release. prefix is optional and is empty by default.

Returns:: The next semantic release for the given version when a list of known git_tags is provided. If a prefix was provided then the next semantic release will be prepended with the prefix. That means if you're setting the next version and you don't want the prefix you'll have to strip it from the returned result.

static String getScriptFromTemplate(String script, Map variables)

This method is for applying variables to a groovy template. It's purpose is to simplify escaping required by the Groovy interpreter when doing more complicated shell scripting such as using regex and needing to substitute Groovy variables. An example of script and variables used by this method would be the following.

import static net.gleske.jervis.tools.AutoRelease.getScriptFromTemplate

String script = '''
#!/bin/bash
set -euxo pipefail

<% tools.each { Map tool -> %>if [ -f "${tool.markerFile}" ]; then
  echo "This project contains code for the build tool ${tool.name}."
fi
<% } %>
'''.trim()

Map variables = [
    tools: [
        [
            name: 'maven',
            markerFile: 'pom.xml'
        ],
        [
            name: 'gradle',
            markerFile: 'build.gradle'
        ],
        [
            name: 'NodeJS npm',
            markerFile: 'package.json'
        ],
        [
            name: 'NodeJS yarn',
            markerFile: 'yarn.lock'
        ],
        [
            name: 'Python setuptools',
            markerFile: 'setup.py'
        ]
    ]
]
println 'Build tool detection script'
println('='*80)
println getScriptFromTemplate(script, variables)
println('='*80)

Which returns the following output.

Build tool detection script
================================================================================
#!/bin/bash
set -euxo pipefail

if [ -f "pom.xml" ]; then
  echo "This project contains code for the build tool maven."
fi
if [ -f "build.gradle" ]; then
  echo "This project contains code for the build tool gradle."
fi
if [ -f "package.json" ]; then
  echo "This project contains code for the build tool NodeJS npm."
fi
if [ -f "yarn.lock" ]; then
  echo "This project contains code for the build tool NodeJS yarn."
fi
if [ -f "setup.py" ]; then
  echo "This project contains code for the build tool Python setuptools."
fi

================================================================================

This example shows that you can pass in Groovy templates with bindings. By using this method yourself you do not need to manage the template engine or binding. Just pass in the template, bindings, and use them through this method.

Parameters:: script - A shell script which is a Groovy template meant to contain variables to be replaced.; variables - A Map of variables to replace in the script.

static boolean isMatched(String expression, String value)

Matches a string against an expression. This is typically used to match branch names.
Parameters:
expression - If the String starts and ends with a /, then it is treated as an expression for regex matching. Otherwise, it is treated as a literal string to match.
value - The value to match against the expression.

Summary:
Method

| Detail:
Method

Jervis API documentation.

[Groovy] Class AutoRelease