You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
221 lines
8.9 KiB
221 lines
8.9 KiB
= 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. |
|
|
|
|
|
|
|
== Using GitHub issues |
|
We use GitHub issues to track bugs and enhancements. If you have a general usage question |
|
please ask on https://stackoverflow.com[Stack Overflow]. The Spring Boot team and the |
|
broader community monitor the https://stackoverflow.com/tags/spring-boot[`spring-boot`] |
|
tag. |
|
|
|
If you are reporting a bug, please help to speed up problem diagnosis by providing as much |
|
information as possible. Ideally, that would include a small |
|
https://github.com/spring-projects/spring-boot-issues[sample project] that reproduces the |
|
problem. |
|
|
|
|
|
|
|
== Sign the Contributor License Agreement |
|
Before we accept a non-trivial patch or pull request we will need you to |
|
https://cla.pivotal.io/sign/spring[sign the Contributor License 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. |
|
|
|
|
|
|
|
== 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 IDEA, you |
|
can use the https://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. |
|
* 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 https://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 |
|
https://www.springsource.com/developer/sts[Spring Tools Suite] or |
|
https://eclipse.org[Eclipse] when working with the code. We use the |
|
https://eclipse.org/m2e/[M2Eclipse] 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 |
|
https://maven.apache.org/run-maven/index.html[Apache Maven] v3.2.3 or above and JDK 1.8. |
|
|
|
|
|
|
|
==== Default build |
|
The project can be built from the root directory using the standard maven command: |
|
|
|
[indent=0] |
|
---- |
|
$ ./mvnw 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` |
|
|
|
If you are rebuilding often, you might also want to skip the tests until you are ready |
|
to submit a pull request: |
|
|
|
[indent=0] |
|
---- |
|
$ ./mvnw 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's 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] |
|
---- |
|
$ ./mvnw -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] |
|
---- |
|
$ ./mvnw -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`. 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 |
|
You can import the Spring Boot code into any Eclipse Mars based distribution. The easiest |
|
way to setup a new environment is to use the Eclipse Installer with the provided |
|
`.setup` file. |
|
|
|
|
|
==== Using the Eclipse Installer |
|
Spring Boot includes a `.setup` files which can be used with the Eclipse Installer to |
|
provision a new environment. To use the installer: |
|
|
|
* Download and run the latest Eclipse Installer from |
|
https://www.eclipse.org/downloads/[eclipse.org/downloads/]. |
|
* Switch to "Advanced Mode" using the drop down menu on the right. |
|
* Select "`Eclipse IDE for Java Developers`" under "`Eclipse.org`" as the product to |
|
install and click "`next`". |
|
* For the "`Project`" click on "`+`" to add a new setup file. Select "`Github Projects`" |
|
and browser for `<checkout>/eclipse/spring-boot-project.setup` from your locally cloned |
|
copy of the source code. Click "`OK`" to add the setup file to the list. |
|
* Double-click on "`Spring Boot`" from the project list to add it to the list that will |
|
be provisioned then click "`Next`". |
|
* Click show all variables and make sure that "`Checkout Location`" points to the locally |
|
cloned source code that you selected earlier. You might also want to pick a different |
|
install location here. |
|
* Click "`Finish`" to install the software. |
|
|
|
Once complete you should find that a local workspace has been provisioned complete with |
|
all required Eclipse plugins. Projects will be grouped into working-sets to make the code |
|
easier to navigate. |
|
|
|
|
|
|
|
==== Manual installation with m2eclipse |
|
If you prefer to install Eclipse yourself we recommend that you use the |
|
https://eclipse.org/m2e/[M2Eclipse] eclipse plugin. 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 additional Eclipse plugins that you can install: |
|
|
|
===== Install the m2eclipse-maveneclipse plugin |
|
* Select "`Help`" -> "`Install New Software`". |
|
* Add `https://dl.bintray.com/philwebb/m2eclipse-maveneclipse` as a site. |
|
* Install "Maven Integration for the maven-eclipse-plugin" |
|
|
|
===== Install the Spring Formatter plugin |
|
* Select "`Help`" -> "`Install New Software`". |
|
* Add `https://dl.bintray.com/philwebb/spring-eclipse-code-formatter/` as a site. |
|
* Install "Spring Code Formatter" |
|
|
|
NOTE: These plugins are optional. Projects can be imported without the plugins, 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] |
|
---- |
|
$ ./mvnw 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 applications 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. |
|
|
|
|