177 lines
7.0 KiB
Plaintext
177 lines
7.0 KiB
Plaintext
= Contributing to Spring Boot
|
|
|
|
Spring Boot is released under the Apache 2.0 license. If you would like to contribute
|
|
something, or simply want to hack on the code this document should help you get started.
|
|
|
|
|
|
|
|
== Sign the Contributor License Agreement
|
|
Before we accept a non-trivial patch or pull request we will need you to sign the
|
|
https://support.springsource.com/spring_committer_signup[contributor's agreement].
|
|
Signing the contributor's agreement does not grant anyone commit rights to the main
|
|
repository, but it does mean that we can accept your contributions, and you will get an
|
|
author credit if we do. Active contributors might be asked to join the core team, and
|
|
given the ability to merge pull requests. Use ``Phillip Webb'' or ``Dave Syer'' in the
|
|
project lead field when you complete the form.
|
|
|
|
|
|
|
|
== Code Conventions and Housekeeping
|
|
None of these is essential for a pull request, but they will all help. They can also be
|
|
added after the original pull request but before a merge.
|
|
|
|
* Use the Spring Framework code format conventions. If you use Eclipse and you follow
|
|
the ``Importing into eclipse'' instructions below you should get project specific
|
|
formatting automatically. You can also import formatter settings using the
|
|
`eclipse-code-formatter.xml` file from the `eclipse` folder. If using IntelliJ, you can
|
|
use the http://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter Plugin]
|
|
to import the same file.
|
|
* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
|
|
`@author` tag identifying you, and preferably at least a paragraph on what the class is
|
|
for.
|
|
* Add the ASF license header comment to all new `.java` files (copy from existing files
|
|
in the project)
|
|
* Add yourself as an `@author` to the .java files that you modify substantially (more
|
|
than cosmetic changes).
|
|
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
|
|
* A few unit tests would help a lot as well -- someone has to do it.
|
|
* If no-one else is using your branch, please rebase it against the current master (or
|
|
other target branch in the main project).
|
|
* When writing a commit message please follow http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions],
|
|
if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
|
|
message (where XXXX is the issue number).
|
|
|
|
|
|
|
|
== Working with the code
|
|
If you don't have an IDE preference we would recommend that you use
|
|
http://www.springsource.com/developer/sts[Spring Tools Suite] or
|
|
http://eclipse.org[Eclipse] when working with the code. We use the
|
|
http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools
|
|
should also work without issue.
|
|
|
|
|
|
|
|
=== Building from source
|
|
To build the source you will need to install
|
|
http://maven.apache.org/run-maven/index.html[Apache Maven] v3.0.6 or above and JDK 1.7.
|
|
|
|
|
|
|
|
==== Default build
|
|
The project can be built from the root directory using the standard maven command:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn clean install
|
|
----
|
|
|
|
NOTE: You may need to increase the amount of memory available to Maven by setting
|
|
a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m`
|
|
|
|
If you are rebuilding often, you might also want to skip the tests until you are ready
|
|
to submit a pull request:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn clean install -DskipTests
|
|
----
|
|
|
|
|
|
|
|
==== Full Build
|
|
Multi-module Maven builds cannot directly include maven plugins that are part of the
|
|
reactor unless they have previously been built. Unfortunately this restriction causes
|
|
some compilations for Spring Boot as we include a maven plugin and use it within the
|
|
samples. The standard build works around this restriction by launching the samples via
|
|
the `maven-invoker-plugin` so that they are not part of the reactor. This works fine
|
|
most of the time, however, sometimes it useful to run a build that includes all modules
|
|
(for example when using `maven-versions-plugin`. We use the full build on our CI servers
|
|
and during the release process.
|
|
|
|
Running a full build is a two phase process.
|
|
|
|
1) Prepare the build
|
|
|
|
Preparing the build will compile and install the `spring-boot-maven-plugin` so that it
|
|
can be referenced during the full build. It also generates a `settings.xml` file that
|
|
enables a `snapshot`, `milestone` or `release` profiles based on the version being
|
|
build. To prepare the build, from the root directory use:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn -P snapshot,prepare install -DskipTests
|
|
----
|
|
|
|
NOTE: You may notice that preparing the build also changes the
|
|
`spring-boot-starter-parent` POM. This is required for our release process to work
|
|
correctly.
|
|
|
|
2) Run the full build
|
|
|
|
Once the build has been prepared, you can run a full build using the following commands:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn -s ./settings.xml -f spring-boot-full-build -P full clean install
|
|
----
|
|
|
|
NOTE: As for the standard build, you may need to increase the amount of memory available
|
|
to Maven by setting a `MAVEN_OPTS` environment variable with the value
|
|
`-Xmx512m -XX:MaxPermSize=128m`. We generate more artifacts when running the full build
|
|
(such as Javadoc jars), so you may find the process a little slower than the standard build.
|
|
|
|
|
|
|
|
=== Importing into eclipse with m2eclipse
|
|
We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with
|
|
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
|
|
marketplace".
|
|
|
|
Spring Boot includes project specific source formatting settings, in order to have these
|
|
work with m2eclipse, we provide an additional eclipse plugin that you can install:
|
|
|
|
* Download `org.eclipse.m2e.maveneclipse.site.zip` from
|
|
https://github.com/philwebb/m2eclipse-maveneclipse/releases.
|
|
* Select `Install new software` from the `help` menu
|
|
* Click `Add...` to add a new repository
|
|
* Click the `Archive...` button
|
|
* Select the `org.eclipse.m2e.maveneclipse.site.zip` that you previously downloaded
|
|
* Install "Maven Integration for the maven-eclipse-plugin"
|
|
|
|
NOTE: This plugin is optional. Projects can be imported without the plugin, your code
|
|
changes just won't be automatically formatted.
|
|
|
|
With the requisite eclipse plugins installed you can select
|
|
`import existing maven projects` from the `file` menu to import the code. You will
|
|
need to import the root `spring-boot` pom and the `spring-boot-samples` pom separately.
|
|
|
|
|
|
|
|
=== Importing into eclipse without m2eclipse
|
|
If you prefer not to use m2eclipse you can generate eclipse project metadata using the
|
|
following command:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn eclipse:eclipse
|
|
----
|
|
|
|
The generated eclipse projects can be imported by selecting `import existing projects`
|
|
from the `file` menu.
|
|
|
|
|
|
|
|
=== Importing into other IDEs
|
|
Maven is well supported by most Java IDEs. Refer to your vendor documentation.
|
|
|
|
|
|
|
|
== Integration tests
|
|
The sample application are used as integration tests during the build (when you
|
|
`mvn install`). Due to the fact that they make use of the `spring-boot-maven-plugin`
|
|
they cannot be called directly, and so instead are launched via the
|
|
`maven-invoker-plugin`. If you encounter build failures running the integration tests,
|
|
check the `build.log` file in the appropriate sample directory.
|
|
|