From 31b123813b64a3ccea98313cdd8c253acbf6a7c8 Mon Sep 17 00:00:00 2001
From: Dave Syer <dsyer@pivotal.io>
Date: Fri, 14 Apr 2017 07:59:40 +0100
Subject: [PATCH] Add docs on version mapping and aliases

---
 .../main/asciidoc/configuration-guide.adoc    | 57 +++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/initializr-docs/src/main/asciidoc/configuration-guide.adoc b/initializr-docs/src/main/asciidoc/configuration-guide.adoc
index 4fac377e..018c549d 100644
--- a/initializr-docs/src/main/asciidoc/configuration-guide.adoc
+++ b/initializr-docs/src/main/asciidoc/configuration-guide.adoc
@@ -312,10 +312,67 @@ and idioms.
 [[dependencies-mappings]]
 ==== Map coordinates according to the Spring Boot version
 
+In addition to a Spring Boot version range for the dependency or a BOM, you can configure
+the version relationships at a finer grained level using version mappings. A dependency or
+BOM has a list of "mappings", each of which consists of a version range, and a set of one
+or more dependency properties to override for those versions of Spring Boot. You can use a
+mapping to switch the version of a dependency, or (better) the BOM, or to change its
+artifact id (if the project changed its packaging) for instance.
+
+Here's an example of a BOM with mappings:
+
+[source,yaml,indent=0]
+----
+initializr:
+  env:
+    boms:
+      cloud-bom:
+        groupId: org.springframework.cloud
+        artifactId: spring-cloud-dependencies
+        order: 50
+        mappings:
+          - versionRange: "[1.2.3.RELEASE,1.3.0.RELEASE)"
+            version: Angel.SR6
+          - versionRange: "[1.3.0.RELEASE,1.4.0.RELEASE)"
+            version: Brixton.SR7
+          - versionRange: "[1.4.0.RELEASE,1.5.x.RELEASE)"
+            version: Camden.SR6
+          - versionRange: "[1.5.0.RELEASE,1.5.x.BUILD-SNAPSHOT)"
+            version: Dalston.RC1
+            repositories: spring-milestones
+          - versionRange: "1.5.x.BUILD-SNAPSHOT"
+            version: Dalston.BUILD-SNAPSHOT
+            repositories: spring-snapshots,spring-milestones
+----
+
+The primary use case here is to map Spring Boot versions to the preferred or supported
+versions of Spring Cloud. You can also see that for the milestone and snapshot BOMs,
+additional repositories are declared because those artifacts are not in the default
+repository.
+
+See below in the section on <<howto-link-boot-version,linking versions>> for more examples.
 
 [[dependencies-alias]]
 ==== Aliases
 
+A dependency has an id (e.g. "web-services"), but it can also be referred to using
+aliases, if those are declared in the metadata. Aliases and ids for dependencies must be
+globally unique (this is not enforced by the software). For example:
+
+[source,yaml,indent=0]
+----
+initializr:
+  dependencies:
+    - name: Other
+      content:
+        - name: Web Services
+          id: web-services
+          aliases:
+            - ws
+----
+
+The same project can now be generated with `dependencies=ws` or
+`dependencies=web-services`.
 
 [[dependencies-repository]]
 ==== Repository