asciidoc/use/buildnumber.adoc

////
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     https://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
////

[*__since 1.4__*]

The `buildnumber` task is similar to the Ant `buildnumber` task, except that it uses Ivy repository to find what is the latest version and calculate a new one for you.

When called, it sets four properties according to what has been found. These properties are:

* `ivy.revision`: the last revision found in the repository
* `ivy.new.revision`: the new revision calculated from the last one (see below)
* `ivy.build.number`: the build number found in the repository
* `ivy.new.build.number`: the new build number calculated from the last one, usually with +1

Build numbers are always numbers (composed of digit characters only).

`ivy.revision` can be not set if no revision was found.

`ivy.build.number` can be not set if no revision was found or if no number was found in it.

`ivy.new.build.number` can be not set if the default new revision to use when no revision is found does not contain some number.

The new revision is calculated using a somewhat complex to explain but very easy to use algorithm, depending on which latest version you asked.

Indeed you can ask for a new revision based upon the latest found for a particular prefix (the revision asked), then the new revision will be the one immediately after with only the prefix in common. If no prefix is set the very latest version is searched.

Examples (suppose the latest version of the module is 1.3.1):

[options="header",cols="5*^.^"]
|=======
| revision asked | ivy.revision | ivy.new.revision | ivy.build.number | ivy.new.build.number
|1.3|1.3.1|1.3.2|1|2
|1|1.3.1|1.4|3|4
|2|not set|2.0|not set|0
||1.3.1|1.3.2|1|2
|=======

Note that when asking for revision 1, you can get a revision 10.0. To avoid that you can use 1. as revision asked, but in this case Ivy won't find revision 1 if its the latest one, and it will thus give 1.0 as new revision. The solution to this problem is to use versions with always the same number of parts (for instance, 1.0.0 instead of 1).

== Attributes

[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|organisation|the organisation of the module for which a new build number should be calculated|Yes
|module|the name of the module for which a new build number should be calculated|Yes
|branch|the branch of the module for which a new build number should be calculated|No, defaults to the default branch for this module
|revision|the revision prefix for which a new build number should be calculated|No, defaults to no prefix (will find the latest version)
|default|the default revision to assume when no revision prefix is asked and no revision is found|No, defaults to 0
|defaultBuildNumber|the default build number to use for the first revision|No, defaults to 0
|revSep|the revision separator to use when no matching revision is found, to separate the revision prefix from the build number|No, defaults to `.`
|prefix|the prefix to use for the property names set (will be `__prefix__.revision`, `__prefix__.new.revision`, ...)|No, defaults to `ivy`
|settingsRef|A reference to Ivy settings that must be used by this task (*__since 2.0__*).|No, `ivy.instance` is taken by default.
|resolver|the name of the resolver to use for build number calculation (*__since 2.1__*)|No, all available resolvers will be used by default.
|=======

== Examples

Here is how it can be used (suppose 1.3.1 is the latest version of Ivy in the repository):

[source,xml]
----
<ivy:buildnumber organisation="apache" module="ivy"/>
----

will set 1.3.1 as revision, 1.3.2 as new revision, 1 as build number and 2 as new build number

'''

[source,xml]
----
<ivy:buildnumber organisation="apache" module="ivy" revision="1.3"/>
----

will set 1.3.1 as revision, 1.3.2 as new revision, 1 as build number and 2 as new build number

'''

[source,xml]
----
<ivy:buildnumber organisation="apache" module="ivy" revision="1.2"/>
----

will set 1.2 as revision, 1.2.1 as new revision, no build number and 1 as new build number

'''

[source,xml]
----
<ivy:buildnumber organisation="apache" module="ivy" revision="1."/>
----

will set 1.3.1 as revision, 1.4 as new revision, 3 as build number and 4 as new build number

'''

[source,xml]
----
<ivy:buildnumber organisation="apache" module="ivy" revision="3."/>
----

will set no revision, 3.0 as new revision, no build number and 0 as new build number

'''

[source,xml]
----
<ivy:buildnumber organisation="apache" module="ivy" revision="1.4-RC" defaultBuildNumber="1" revSep=""/>
----

If called while no release candidate is in the repository, will set ivy.revision to 1.4-RC1. Then it will increment each time, 1.4-RC2, 1.4-RC3, and so on.