Add docs for starter pom usage

README.md

@@ -215,6 +215,9 @@ Create a `pom.xml` to import the appropriate Spring Boot starters:
 > a [plugin](spring-boot-tools/spring-boot-gradle-plugin/README.md) that can help you
 > package an executable JAR.
 
+More detail about the Maven plugin, and how to build a Spring Boot
+project with Maven is available in the [starter docs](spring-boot-starters/README.md).
+
 <span id="quick-start-java-example"></span>
 ### Quick start Java example
 Here is the main class for a simple web application (just save the content to

spring-boot-starters/README.md

@@ -1,4 +1,211 @@
 # Spring Boot - Starters
 
-> We are currently still working on documentation for Spring Boot. Please check back
+Starters are a set of convenient dependency descriptors that you can
-> in the future.
+include in your application. You get a one-stop-shop for all the
+Spring and related technology that you need without having to hunt
+through sample code and copy paste loads of dependency
+descriptors. For example, if you want to get started using Spring and
+JPA for database access just include the
+`spring-boot-starter-data-jpa` dependency in your project, and you are
+good to go.  The starters contain a lot of the dependencies that you
+need to get a project up and running quickly and with a consistent,
+supported set of managed transitive dependencies.
+
+## Building a Spring Boot Project with Maven
+
+The quickest way to get started with a new project is to use the
+spring-boot-starter-parent, e.g.
+
+```xml
+	<!-- Inherit defaults from Spring Boot -->
+	<parent>
+		<groupId>org.springframework.boot</groupId>
+		<artifactId>spring-boot-starter-parent</artifactId>
+		<version>1.0.0.RC3</version>
+	</parent>
+```
+
+The parent pom adds two main fetaures to your project:
+
+* dependency management configuration, so you don't have to specify
+  versions or excludes with your own dependencies, as long as they are
+  part of the Spring Boot stack
+  
+* plugin configuration, so you don't have to configure some common
+  settings in the main Maven plugins used to get a project off the
+  ground (e.g. the
+  [Spring Boot Maven plugin](../spring-boot-tools/spring-boot-maven-plugin/README.md))
+  
+As an example, if you want to build a simple RESTful web service with
+embedded Tomcat, you only need one dependency:
+
+```xml
+	<dependencies>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-web</artifactId>
+		</dependency>
+	</dependencies>
+```
+
+And if you want to use the Spring Boot plugin to package the project
+as an executable JAR (or run it from source code), you only need to
+add the plugin (not configure it, unless you want to change the
+settings in the parent):
+
+```xml
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.springframework.boot</groupId>
+				<artifactId>spring-boot-maven-plugin</artifactId>
+			</plugin>
+		</plugins>
+    </build>
+```
+
+If you need to access milestone or snapshot builds from Spring
+projects, you can optionallyt add repositories, as follows:
+
+```xml
+	<repositories>
+		<repository>
+			<id>spring-snapshots</id>
+			<url>http://repo.spring.io/snapshot</url>
+			<snapshots><enabled>true</enabled></snapshots>
+		</repository>
+		<repository>
+			<id>spring-milestones</id>
+			<url>http://repo.spring.io/milestone</url>
+			<snapshots><enabled>true</enabled></snapshots>
+		</repository>
+	</repositories>
+	<pluginRepositories>
+		<pluginRepository>
+			<id>spring-snapshots</id>
+			<url>http://repo.spring.io/snapshot</url>
+		</pluginRepository>
+		<pluginRepository>
+			<id>spring-milestones</id>
+			<url>http://repo.spring.io/milestone</url>
+		</pluginRepository>
+	</pluginRepositories>
+```
+
+The repositories cannot all be defined in the parent (at least one
+will be required to resolve the parent itself).
+
+### Using Your Own Parent POM
+
+If you don't want to use the Spring Boot starter parent, you can use
+your own and still keep the benefit of the dependency management (but
+not the plugin management) using
+["scope=import"](http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html). Example:
+
+```xml
+<dependencyManagement>
+  <dependencies>
+	<dependency>
+		<groupId>org.springframework.boot</groupId>
+		<artifactId>spring-boot-starter-parent</artifactId>
+		<version>1.0.0.RC3</version>
+        <scope>import</scope>
+	</dependency>
+  </dependencies>
+</dependencyManagement>
+```
+
+(It actually doesn't matter if you use "spring-boot-starter-parent" or
+"spring-boot-dependencies".)
+
+### Samples
+
+All the
+[Spring Boot Samples](https://github.com/spring-projects/spring-boot-samples)
+come with a `pom.xml`, but they use a different parent to
+spring-boot-starter-parent (although that pom is one of their
+ancestors). Other useful places to get clean projects with a
+`pom.xml` that works as quickly as possible:
+
+* The
+[Getting Started Guides on spring.io](http://spring.io/guides/gs) are
+all available in [github](https://github.com/spring-guides), or you
+can copy paste from the guides themselves (all the code is on the web
+page).
+
+* The same guides are available as working projects in
+[Spring Tool Suite](http://spring.io/tools/sts)(STS) (an Eclipse
+plugin feature set), and so is a starter project template generator
+(via `File->New->Spring Starter Project`).
+
+* The Spring Starter Project feature in STS is backed by a web
+application at [start.spring.io](http://start.spring.io), which you
+can also use yourself to download ZIP files of the starter projects.
+
+## Building With Gradle
+
+If you prefer to build your project with Gradle then similar features
+are available to you as to Maven users. The starter projects work in
+exactly the same way, for instance, so a typical project might have a
+`build.gradle` like this:
+
+```groovy
+buildscript {
+
+    ext {
+		springBootVersion = '1.0.0.RC3'
+	}
+
+    repositories {
+	    mavenCentral()
+		maven { url "http://repo.springsource.org/libs-milestone" }
+	}
+	dependencies {
+		classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
+	}
+}
+
+
+apply plugin: 'java'
+apply plugin: 'spring-boot'
+
+jar {
+	baseName = 'spring-boot-sample-simple'
+	version =  '0.5.0'
+}
+
+repositories {
+	mavenCentral()
+	maven { url "http://repo.springsource.org/libs-milestone" }
+}
+
+dependencies {
+	compile("org.springframework.boot:spring-boot-starter-web")
+	testCompile("org.springframework.boot:spring-boot-starter-test")
+}
+
+task wrapper(type: Wrapper) { gradleVersion = '1.6' }
+```
+
+This build is for a simple RESTful web service (with embedded
+Tomcat). Notice that the dependencies do not have explicit version
+numbers. This works for Spring Boot dependencies, but also anything
+else that is explicitly managed by the Spring Boot Starter parent.
+
+Versionless dependency resolution is a feature of the
+[Spring Boot Gradle Plugin](../spring-boot-tools/spring-boot-maven-plugin/README.md),
+which also gives you a "run from source" feature ("gradle bootRun")
+and an enhanced JAR/WAR packaging feature for executable archives
+("gradle build").
+
+### Samples
+
+Most of the samples mentioned above for Maven users are also buildable
+using Gradle. Only some of the
+[Spring Boot Samples](https://github.com/spring-projects/spring-boot-samples)
+come with a `build.gradle`. The Spring Starter Project feature in STS
+produces a Maven project. But web application at
+[start.spring.io](http://start.spring.io) can generate Gradle build
+files for the same projects (just download it with a browser or
+command line).
+