Commit 6618b599 authored by Patrik Dufresne's avatar Patrik Dufresne

Add a README file

parent f17c4219
Pipeline #139192443 passed with stages
in 41 seconds
# maven-scm-version
This project handle managing version for Maven projects based on SCM metadata. Instead of defining the version in `pom.xml`, this project will provide a version number based on current SCM state. This project gets its inspiration from [setuptools_scm](https://github.com/pypa/setuptools_scm) for Python.
Usually, the version number of maven project is kept in `pom.xml` in a static way. Basically, the users need to update the `pom.xml` file for every release. With continuous integration taking more space, that way of working is not flexible enough. It doesn't follow continuous integration principle where any revision may be promoted to production environment. That's where maven-scm-version come to the rescue.
## How to use maven-scm-version
In your `pom.xml` you need to change the `<version>` to make use of [`${revision}`](https://maven.apache.org/maven-ci-friendly.html).
```
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.example.project</groupId>
<artifactId>ci-friendly-project</artifactId>
<name>CI Friendly Project</name>
<version>${revision}</version>
...
</project>
```
Next time you need to compile your project, you can do so like this:
```
export REVISION="$(curl https://raw.githubusercontent.com/ikus060/maven-scm-version/master/version.sh | bash -)"
mvn -Drevision=$REVISION clean package
```
Since your goal is to setup continuous integration pipeline, you should make use of this command line in your preferred CICD tools like Jenkins or Gitlab-CI. Here's an example for `.gitlab-ci.yml`:
```
image: maven:3-jdk-7
variables:
MAVEN_OPTS: "-Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=WARN
-Dorg.slf4j.simpleLogger.showDateTime=true
-Djava.awt.headless=true
-Dmaven.repo.local=.m2/repository"
# Cache downloaded dependencies and plugins between builds.
cache:
paths:
- .m2/repository
stages:
- test
- deploy
before_script:
- export REVISION="$(curl https://raw.githubusercontent.com/ikus060/maven-scm-version/master/version.sh | bash -)"
- echo "REVISION=$VERSION"
test:
stage: test
script:
- mvn -B -Drevision=${REVISION} clean verify
deploy:
stage: deploy
script:
- mvn -B -Drevision=${REVISION} -DskipTests clean install deploy
```
## Version number scheme
By default, maven-scm-version take 3 things in consideration:
1. the latest tag
2. the distance to the latest tag (e.g. number of commit since latest tag)
3. workspace state (e.g.: uncommitted changes)
Then, use that information to provide a version number following this principle:
* no distance and clean:
* {tag}
* distance and clean:
* {next_version}-{distance}-g{revision hash}
* no distance and not clean:
* {tag}-dYYMMDD
* distance and not clean:
* {next_version}-{distance}-g{revision hash}.dYYMMDD
## Limitation
Current implementation only support git scm.
## Background Story
The proper way to provide this feature would be to develop a specific maven plugin. Similar to [maven-buildnumber](http://www.mojohaus.org/buildnumber-maven-plugin/), but maven doesn't provide good enough integration to change the version.
By using shell script, you are not restricted. You may also use the same script to generate version of all sorts of projects in a similar way.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment