From 1f5d7dc77695e046e289979b21c4d68b0a2786ce Mon Sep 17 00:00:00 2001
From: Dave Syer <dsyer@pivotal.io>
Date: Thu, 13 Apr 2017 09:58:21 +0100
Subject: [PATCH] Add some material on BOMs

---
 .../main/asciidoc/configuration-guide.adoc    | 81 +++++++++++++++++--
 1 file changed, 75 insertions(+), 6 deletions(-)

diff --git a/initializr-docs/src/main/asciidoc/configuration-guide.adoc b/initializr-docs/src/main/asciidoc/configuration-guide.adoc
index 424d8977..4444b474 100644
--- a/initializr-docs/src/main/asciidoc/configuration-guide.adoc
+++ b/initializr-docs/src/main/asciidoc/configuration-guide.adoc
@@ -295,8 +295,82 @@ The rest of this section will detail the other configuration options.
 
 If the dependency is not available on Maven Central (or whatever default repository that
 is configured on your end), you can also add a <<dependencies-repository,reference to a
-repository>>.
+repository>>. A repository is declared at the top level (under `env`) and given an id via
+the key in the configuration. Example
 
+[source,yml,indent=0,subs="verbatim,attributes"]
+----
+initializr:
+  env:
+    repositories:
+      my-api-repo-1:
+        name: repo1
+        url: http://example.com/repo1
+----
+
+he repository can then be referred back to in a dependency
+
+[source,yml,subs="verbatim,attributes"]
+----
+initializr:
+  dependencies:
+    - name: Other
+      content:
+        - name: Foo
+          groupId: org.acme
+          artifactId: foo
+          version: 1.3.5
+          repository: my-api-repo-1
+----
+
+It is usually preferable to have a BOM for every dependency, and attach the repository to
+the BOM instead.
+
+[[create-instance-boms]]
+=== Configuring Bill of Materials
+
+A Bill of Materials (BOM) is a special `pom.xml`, deployed to a Maven repository, and use
+to control dependency management for a set of related artifacts. In the Spring Boot
+ecosystem we usually use the suffix "-dependencies" on the artifact id of a BOM. In other
+projects we see "-bom". It is recommended that all dependencies are included in a BOM of
+some sort, since they provide nice high level features for users of the dependency. It is
+also important that 2 BOMs used in a project do not contain conflicting versions for the
+same dependency, so the best practice is to look at the existing BOMs in the Initializr
+before you add a new one, and make sure that you aren't adding a conflict. Maven (3.5)
+will report conflicts when it builds a project containing the two BOMs, even if the
+dependency that conflicts is not used.
+
+In the Initializr a BOM is declared at the `env` level, and given an id through the
+configuration key. Example:
+
+[source,yml,subs="verbatim,attributes"]
+----
+initializr:
+  env:
+    boms:
+      my-api-bom:
+        groupId: org.acme
+        artifactId: my-api-dependencies
+        version: 1.0.0.RELEASE
+        repositories: my-api-repo-1
+----
+
+If a BOM requires a special, non-default repository, then it can be referred to here,
+instead of having to explicitly list the repository again for each dependency. A
+dependency, or a dependency group, can declare that it requires the use of one or more BOMs by referring to the id. Example:
+
+[source,yml,subs="verbatim,attributes"]
+----
+initializr:
+  dependencies:
+    - name: Other
+      content:
+        - name: My API
+          id : my-api
+          groupId: org.acme
+          artifactId: my-api
+          bom: my-api-bom
+----
 
 [[dependencies-facet]]
 ==== Facets
@@ -304,7 +378,6 @@ repository>>.
 [[create-instance-dependencies-link]]
 ==== Links
 
-
 [[create-instance-dependencies-search]]
 ==== Improve search results
 
@@ -315,10 +388,6 @@ Weight + keywords
 === Configuring Repositories
 
 
-[[create-instance-boms]]
-=== Configuring Bill of Materials
-
-
 [[configuration-howto]]
 == '`How-to`' guides