Improve documentation for dependency version declaration

This documents the version syntax (mostly copied from the version
constraint javadocs) as well as the new strict version short-hand
notation.

Author: melix

subprojects/docs/src/docs/userguide/dep-man/02-declaring-dependency-versions/declaring_dependency_versions.adoc

@@ -1,6 +1,8 @@
 [[declaring-dependency-versions]]
 = Declaring dependency versions
 
+include::single_versions.adoc[leveloffset=+1]
+
 include::rich_versions.adoc[leveloffset=+1]
 
 [[sec:declaring_without_version]]

subprojects/docs/src/docs/userguide/dep-man/02-declaring-dependency-versions/rich_versions.adoc

@@ -4,6 +4,7 @@
 Gradle supports a rich model for declaring versions, which allows to combine different level of version information.
 The terms and their meaning are explained below, from the strongest to the weakest:
 
+[[sec:strict-version]]
 `strictly`::
 Any version not matched by this version notation will be excluded.
 This is the strongest version declaration.
@@ -12,13 +13,15 @@ This term supports dynamic versions.
 +
 When defined, overrides previous `require` declaration and clears previous `reject`.
 
+[[sec:required-version]]
 `require`::
 Implies that the selected version cannot be lower than what `require` accepts but could be higher through conflict resolution, even if higher has an exclusive higher bound.
 This is what a direct version on a dependency translates to.
 This term supports dynamic versions.
 +
 When defined, overrides previous `strictly` declaration and clears previous `reject`.
 
+[[sec:preferred-version]]
 `prefer`::
 This is a very soft version declaration.
 It applies only if there is no stronger non dynamic opinion on a version for the module.
@@ -28,6 +31,7 @@ Definition can complement `strictly` or `require`.
 
 There is also an additional term outside of the level hierarchy:
 
+[[sec:rejected-version]]
 `reject`::
 Declares that specific version(s) are not accepted for the module.
 This will cause dependency resolution to fail if the only versions selectable are also rejected.

subprojects/docs/src/docs/userguide/dep-man/02-declaring-dependency-versions/single_versions.adoc

@@ -0,0 +1,73 @@
+[[single-version-declarations]]
+= Single version declarations
+
+The simplest version declaration is a _simple string_ representing the version to use.
+Gradle supports different ways of declaring a version string:
+
+* An exact version: e.g. `1.3`, `1.3.0-beta3`, `1.0-20150201.131010-1`
+* A Maven-style version range: e.g. `[1.0,)`, `[1.1, 2.0)`, `(1.2, 1.5]`
+** The `[` and `]` symbols indicate an inclusive bound; `(` and `)` indicate an exclusive bound.
+** When the upper or lower bound is missing, the range has no upper or lower bound.
+** The symbol `]` can be used instead of `(` for an exclusive lower bound, and `[` instead of `)` for exclusive upper bound. e.g `]1.0, 2.0[`
+* A _prefix_ version range: e.g. `1.+`, `1.3.+`
+** Only versions exactly matching the portion before the `+` are included.
+** The range `+` on it's own will include any version.
+* A `latest-status` version: e.g. `latest.integration`, `latest.release`
+** Will match the highest versioned module with the specified status. See link:{javadocPath}/org/gradle/api/artifacts/ComponentMetadata.html#getStatus--[ComponentMetadata.getStatus()].
+* A Maven `SNAPSHOT` version identifier: e.g. `1.0-SNAPSHOT`, `1.4.9-beta1-SNAPSHOT`
+
+== Version ordering
+
+Versions have an implicit ordering. Version ordering is used to:
+* Determine if a particular version is included in a range.
+* Determine which version is 'newest' when performing conflict resolution.
+
+Versions are ordered based on the following rules:
+
+* Each version is split into it's constituent "parts":
+** The characters `[. - _ +]` are used to separate the different "parts" of a version.
+** Any part that contains both digits and letters is split into separate parts for each: `1a1 == 1.a.1`
+** Only the parts of a version are compared. The actual separator characters are not significant: `1.a.1 == 1-a+1 == 1.a-1 == 1a1`
+* The equivalent parts of 2 versions are compared using the following rules:
+** If both parts are numeric, the highest numeric value is **higher**: `1.1` < `1.2`
+** If one part is numeric, it is considered **higher** than the non-numeric part: `1.a` < `1.1`
+** If both are not numeric, the parts are compared **alphabetically, case-sensitive**: `1.a` < `1.A` < `1.b` < `1.B`
+** A version with an extra numeric part is considered **higher** than a version without: `1.1` < `1.1.0`
+** A version with an extra non-numeric part is considered **lower** than a version without: `1.1` < `1.1.a`
+* Certain string values have special meaning for the purposes of ordering:
+** The string `dev` is consider **lower** than any other string part: `1.0-dev` < `1.0-alpha` < `1.0-rc`.
+** The strings `rc`, `release` and `final` are considered **higher** than any other string part (sorted in that order): `1.0-zeta` < `1.0-rc` < `1.0-release` < `1.0-final` < `1.0`.
+** The string `SNAPSHOT` has **no special meaning**, and is sorted alphabetically like any other string part: `1.0-alpha` < `1.0-SNAPSHOT` < `1.0-zeta` < `1.0-rc` < `1.0`.
+** Numeric snapshot versions have **no special meaning**, and are sorted like any other numeric part: `1.0` < `1.0-20150201.121010-123` < `1.1`.
+
+== Simple version declaration semantics
+
+When you declare a version using the short-hand notation, for example:
+
+.A simple declaration
+====
+include::sample[dir="userguide/dependencyManagement/declaringDependencies/concreteVersion/groovy",files="build.gradle[tags=required-version]"]
+include::sample[dir="userguide/dependencyManagement/declaringDependencies/concreteVersion/kotlin",files="build.gradle.kts[tags=required-version]"]
+====
+
+Then the version is considered a <<rich_versions.adoc#sec:required-version,required version>> which means that it should _minimally_ be `1.7.15` but can be upgraded by the engine (optimistic upgrade).
+
+There is, however, a shorthand notation for <<rich_versions.adoc#sec:strict-version,strict versions>>, using the `!!` notation:
+
+.Shorthand notation for strict dependencies
+====
+include::sample[dir="userguide/dependencyManagement/declaringDependencies/concreteVersion/groovy",files="build.gradle[tags=strict-shorthand]"]
+include::sample[dir="userguide/dependencyManagement/declaringDependencies/concreteVersion/kotlin",files="build.gradle.kts[tags=strict-shorthand]"]
+====
+
+A strict version _cannot be upgraded_ and overrides whatever transitive dependencies originating from this dependency provide.
+It is recommended to use ranges for strict versions.
+
+The notation `[1.7, 1.8[!!1.7.25` above is equivalent to:
+
+* strictly `[1.7, 1.8[`
+* prefer `1.7.25`
+
+which means that the engine **must** select a version between 1.7 (included) and 1.8 (excluded), and that if no other component in the graph needs a different version, it should _prefer_ `1.7.25`.
+
+The section below explains the semantics of rich version constraints in details.

subprojects/docs/src/samples/userguide/dependencyManagement/declaringDependencies/concreteVersion/groovy/build.gradle

@@ -32,6 +32,37 @@ dependencies {
 }
 // end::rich-version[]
 
+/*
+// tag::required-version[]
+dependencies {
+    implementation('org.slf4j:slf4j-api:1.7.15')
+}
+// end::required-version[]
+
+// tag::strict-shorthand[]
+dependencies {
+    // short-hand notation with !!
+    implementation('org.slf4j:slf4j-api:1.7.15!!')
+    // is equivalent to
+    implementation("org.slf4j:slf4j-api") {
+        version {
+           strictly '1.7.15'
+        }
+    }
+    
+    // or...
+    implementation('org.slf4j:slf4j-api:[1.7, 1.8[!!1.7.25')
+    // is equivalent to
+    implementation('org.slf4j:slf4j-api') {
+        version {
+           strictly '[1.7, 1.8['
+           prefer '1.7.25'
+        }
+    }
+}
+// end::strict-shorthand[]
+ */
+
 task copyLibs(type: Copy) {
     from configurations.compileClasspath
     into "$buildDir/libs"

subprojects/docs/src/samples/userguide/dependencyManagement/declaringDependencies/concreteVersion/kotlin/build.gradle.kts

@@ -36,3 +36,34 @@ tasks.register<Copy>("copyLibs") {
     from(configurations.compileClasspath)
     into("$buildDir/libs")
 }
+
+/*
+// tag::required-version[]
+dependencies {
+    implementation("org.slf4j:slf4j-api:1.7.15")
+}
+// end::required-version[]
+
+// tag::strict-shorthand[]
+dependencies {
+    // short-hand notation with !!
+    implementation("org.slf4j:slf4j-api:1.7.15!!")
+    // is equivalent to
+    implementation("org.slf4j:slf4j-api") {
+        version {
+           strictly("1.7.15")
+        }
+    }
+    
+    // or...
+    implementation("org.slf4j:slf4j-api:[1.7, 1.8[!!1.7.25")
+    // is equivalent to
+    implementation("org.slf4j:slf4j-api") {
+        version {
+           strictly([1.7, 1.8[")
+           prefer("1.7.25")
+        }
+    }
+}
+// end::strict-shorthand[]
+ */