diff --git a/src/site/apt/version-rules.apt.vm b/src/site/apt/version-rules.apt.vm deleted file mode 100644 index eb28a0adf..000000000 --- a/src/site/apt/version-rules.apt.vm +++ /dev/null @@ -1,253 +0,0 @@ - ~~ 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 - ~~ - ~~ http://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. - - ----- - Version number rules - ----- - Stephen Connolly - ------ - 2012-11-14 - ------ - -Version number rules - -* Introduction - - <> The limitations explained in this paragraph were true in Maven 2.x, but have been <> in Maven 3.x (see - {{{https://cwiki.apache.org/confluence/display/MAVENOLD/Versioning}Maven Versioning Wiki page}} for more details) - - The current implementation of - {{{http://maven.apache.org/ref/current/maven-artifact/xref/org/apache/maven/artifact/versioning/DefaultArtifactVersion.html}<<>>}} - in the core of Maven expects that version numbers will have a very specific format: - - <<< . . - >>> - - Where , , and are all numeric and - is a string. If your version number does not match this format, then the entire version number is treated as being - the . - - If your version numbers do not match this scheme, you may face issues with - - * version ranges (unfortunately there is nothing that the <<>> can do to help you with - your problems with version ranges and your version numbering scheme... well you could replace your - version ranges with properties and use the update-properties goal) - - * goals in this plugin that sort versions, for example update-properties (you can do things to help with these - kinds of problems) - - The <<>> knows three rules for comparing version numbers: - - [<<>>] The standard Maven 2.x version numbering scheme. - - [<<>>] An alternative version numbering scheme with no "special" qualifiers. - - The <<>> will assume that all version numbers follow the <<>> scheme unless you tell - it otherwise. - -* Rules.xml - - To specify the version schemes to use, you may define a {{{./rule.html}rule-set xml file}}, use the <<>> - element in the <<>> plugin configuration, or specify ignored versions via - the <<>> property. - -** Using the <<>> file - - The <<>> file should conform to the xsd specified in the example below. - ---- - - - - - - - - ---- - - The rule-set files must match the {{{./xsd/rule-2.0.0.xsd}XSD schema}}. - - You can then use the <<>> parameter to specify the rule-set to be used by the - <<>>. - - Note: the <<>> attribute in the <<>> elements has a lazy <<<.*>>> at the end, such that - <<>> will match <<>>, <<>>, <<>>, etc. - -** Using the <<>> element in the POM - - As an alternative to providing a separate <<>> file, starting with version <<<2.13.0>>> it is possible - to provide the <<>> element directly in the POM. The structure is somewhat simpler to - the <<>> file: - ---- - - ... - - ... - - ... - - org.codehaus.mojo - versions-maven-plugin - ${pluginVersion} - - - - - - - 1.0.0 - - - - regex - (.+-SNAPSHOT|.+-M\d) - - - regex - .+-(alpha|beta) - - - - - - - - - org.codehaus.mojo - - - - ... - - - - maven - - - ---- - -** Using the <<>> property - - The <<>> property can list *comma-separated* list of global version **regex** patterns, which - will be ignored when considering available versions. - - Examples: - - * <<<1.0.0>>> - - * <<<.+-SNAPSHOT>>> - - * <<<(.+-SNAPSHOT|.+-M\d),.+-(alpha|beta),3.0.0>>> - -** Ignoring certain versions - - It is possible to ignore versions on a global and on a per-rule basis. - - The other methods (via the <<<>>> element and via the <<>>) property have been - explained above. The described - ---- - - - .*-beta - - - - - .*-RELEASE - 2.1.0 - - - - ---- - - Note: it is possible to ignore versions using regular expressions. - - If you have your ruleset xml file hosted at, for example, http://www.mycompany.com/maven-version-rules.xml - then the following configuration in your corporate pom would ensure that all projects use this rule set. - ---- - - ... - - ... - - ... - - org.codehaus.mojo - versions-maven-plugin - ${pluginVersion} - - ... - http://www.mycompany.com/maven-version-rules.xml - ... - - - ... - - ... - - ... - ---- - - You can provide your ruleset xml file also within a jar, if you want to distribute - your ruleset xml as Maven artifact. Therefore you have to declare the containing - jar as direct dependency of the <> and to use classpath - as protocol. - ---- - - ... - - ... - - ... - - org.codehaus.mojo - versions-maven-plugin - ${pluginVersion} - - ... - classpath:///package/foo/bar/rules.xml - ... - - - - com.mycompany - version-rules - 1.0 - - - - ... - - ... - - ... - ---- \ No newline at end of file diff --git a/src/site/markdown/version-rules.md.vm b/src/site/markdown/version-rules.md.vm new file mode 100644 index 000000000..2c7c8fb13 --- /dev/null +++ b/src/site/markdown/version-rules.md.vm @@ -0,0 +1,249 @@ +title: Version Rules +autor: Stephen Connolly +date: 2012-11-14 + + + +## Velocity uses # as a prefix for macros and ## as a prefix for comments +#set($h1 = '#') +#set($h2 = '##') +#set($h3 = '###') +#set($h4 = '####') + +$h1 Version number rules + +$h2 Introduction + +**Notice:** The limitations explained in this paragraph were true in Maven 2.x, but have been **fixed** in Maven 3.x (see +[Maven Versioning Wiki page](https://cwiki.apache.org/confluence/display/MAVENOLD/Versioning) for more details) + +The current implementation of +[DefaultArtifactVersion](https://maven.apache.org/ref/current/maven-artifact/xref/org/apache/maven/artifact/versioning/DefaultArtifactVersion.html) +in the core of Maven expects that version numbers will have a very specific format: + +` . . - ` + +Where *MajorVersion*, *MinorVersion*, *IncrementalVersion* and *BuildNumber* are all numeric and *Qualifier* +is a string. If your version number does not match this format, then the entire version number is treated as being +the *Qualifier*. + +If your version numbers do not match this scheme, you may face issues with +- version ranges (unfortunately there is nothing that the `versions-maven-plugin` can do to help you with + your problems with version ranges and your version numbering scheme... well you could replace your + version ranges with properties and use the update-properties goal) +- goals in this plugin that sort versions, for example update-properties (you can do things to help with these + kinds of problems) + +The `versions-maven-plugin` knows three rules for comparing version numbers: +- *maven*, The standard Maven 2.x and 3.x version numbering scheme. +- *numeric*, An alternative version numbering scheme with no "special" qualifiers. +- *mercury*, An alternative version numbering scheme, now defunct. + +The `versions-maven-plugin` will assume that all version numbers follow the `maven` scheme unless you tell +it otherwise. + +$h2 Rules.xml + +To specify the version schemes to use, you may define a [rule-set xml file](./rule.html), use the `ruleSet` +element in the `versions-maven-plugin` plugin configuration, or specify ignored versions via +the `maven.version.ignore` property. + +$h3 Using the `Rules.xml` file + +The `rules.xml` file should conform to the xsd specified in the example below. + +```xml + + + + + + + + +``` + +The rule-set files must match the [XSD schema](./xsd/rule-2.0.0.xsd). + +You can then use the `rulesUri` parameter to specify the rule-set to be used by the +`versions-maven-plugin`. + +Note: the `groupId` attribute in the `rule` elements has a lazy `.*` at the end, such that +`com.mycompany` will match `com.mycompany`, `com.mycompany.foo`, `com.mycompany.foo.bar`, etc. + +$h3 Using the `ruleSet` element in the POM + +As an alternative to providing a separate `rules.xml` file, starting with version `2.13.0` it is possible +to provide the `ruleSet` element directly in the POM. The structure is somewhat simpler to +the `rules.xml` file: + +```xml + + ... + + ... + + ... + + org.codehaus.mojo + versions-maven-plugin + ${pluginVersion} + + + + + + + 1.0.0 + + + + regex + (.+-SNAPSHOT|.+-M\d) + + + regex + .+-(alpha|beta) + + + + + + + + + org.codehaus.mojo + + + + ... + + + + maven + + + +``` + +$h3 Using the `maven.version.ignore` property + +The `maven.version.ignore` property can list *comma-separated* list of global version **regex** patterns, which +will be ignored when considering available versions. + +Examples: +- `1.0.0` +- `.+-SNAPSHOT` +- `(.+-SNAPSHOT|.+-M\d),.+-(alpha|beta),3.0.0` + +$h3 Ignoring certain versions + +It is possible to ignore versions on a global and on a per-rule basis. + +The other methods (via the `` element and via the `maven.version.ignore`) property have been +explained above. The described + +```xml + + + .*-beta + + + + + .*-RELEASE + 2.1.0 + + + + +``` + +Note: it is possible to ignore versions using regular expressions. + +If you have your ruleset xml file hosted at, for example, http://www.mycompany.com/maven-version-rules.xml +then the following configuration in your corporate pom would ensure that all projects use this rule set. + +```xml + + ... + + ... + + ... + + org.codehaus.mojo + versions-maven-plugin + ${pluginVersion} + + ... + http://www.mycompany.com/maven-version-rules.xml + ... + + + ... + + ... + + ... + +``` + +You can provide your ruleset xml file also within a jar, if you want to distribute +your ruleset xml as Maven artifact. Therefore you have to declare the containing +jar as direct dependency of the **versions-maven-plugin** and to use classpath +as protocol. + +```xml + + ... + + ... + + ... + + org.codehaus.mojo + versions-maven-plugin + ${pluginVersion} + + ... + classpath:///package/foo/bar/rules.xml + ... + + + + com.mycompany + version-rules + 1.0 + + + + ... + + ... + + ... + +```