mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-08-29 03:06:45 +08:00
208 lines
8.9 KiB
Plaintext
Executable File
208 lines
8.9 KiB
Plaintext
Executable File
= 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.
|
|
|
|
|
|
|
|
== Code of Conduct
|
|
This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of
|
|
conduct]. By participating, you are expected to uphold this code. Please report
|
|
unacceptable behavior to spring-code-of-conduct@pivotal.io.
|
|
|
|
|
|
|
|
== 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 sample project that
|
|
reproduces the problem.
|
|
|
|
|
|
|
|
== Reporting Security Vulnerabilities
|
|
If you think you have found a security vulnerability in Spring Boot please *DO NOT*
|
|
disclose it publicly until we've had a chance to fix it. Please don't report security
|
|
vulnerabilities using GitHub issues, instead head over to https://pivotal.io/security and
|
|
learn how to disclose them responsibly.
|
|
|
|
|
|
|
|
== 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.
|
|
|
|
* We use the https://github.com/spring-io/spring-javaformat/[Spring JavaFormat] project
|
|
to apply code formatting conventions. If you use Eclipse and you follow the '`Importing
|
|
into eclipse`' instructions below you should get project specific formatting
|
|
automatically. You can also install the
|
|
https://github.com/spring-io/spring-javaformat/#intellij-idea[Spring JavaFormat IntelliJ
|
|
Plugin] or format the code from the Gradle build by running
|
|
`./gradlew format`. Note that if you have format violations in `buildSrc`, you can fix
|
|
them by running `./gradlew -p buildSrc format` from the project root directory.
|
|
* The build includes checkstyle rules for many of our code conventions. Run
|
|
`./gradlew checkstyleMain checkstyleTest` if you want to check you changes are
|
|
compliant.
|
|
* 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://spring.io/tools[Spring Tool Suite] or
|
|
https://eclipse.org[Eclipse] when working with the code. We use the
|
|
https://projects.eclipse.org/projects/tools.buildship[Buildship] Eclipse plugin for Gradle
|
|
support. Other IDEs and tools should also work without issue.
|
|
|
|
|
|
|
|
=== Building from Source
|
|
Spring Boot source can be built from the command line using https://gradle.org[Gradle] on
|
|
JDK 1.8 or above. We include https://docs.gradle.org/current/userguide/gradle_wrapper.html[Gradle's
|
|
wrapper scripts] (`./gradlew` or `gradlew.bat`) that you can run rather than needing to
|
|
install Gradle locally.
|
|
|
|
The project can be built from the root directory using the standard Gradle command:
|
|
|
|
[indent=0]
|
|
----
|
|
$ ./gradlew build
|
|
----
|
|
|
|
|
|
|
|
=== Importing into Eclipse
|
|
You can import the Spring Boot code into any Eclipse 2019-12-based distribution. The
|
|
easiest way to setup a new environment is to use the Eclipse Installer with the provided
|
|
`spring-boot-project.setup` file (in the `/eclipse` folder).
|
|
|
|
|
|
|
|
==== 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
|
|
https://www.eclipse.org/downloads/packages/installer[Eclipse Installer].
|
|
* 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, `2019-12` as the product version, and click "`next`".
|
|
* For the "`Project`" click on "`+`" to add a new setup file. Select "`Github Projects`"
|
|
and browse 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.
|
|
|
|
TIP: If you see import errors with `com.sun` packages make sure you have setup a valid
|
|
`JavaSE-1.8` environment. From preferences select "`Java`", "`Installed JREs`",
|
|
"`Execution Environments`" and make sure "`JavaSE-1.8`" points to a Java 1.8
|
|
install (we use AdoptOpenJDK on our CI).
|
|
|
|
|
|
|
|
==== Manual Installation with Buildship
|
|
If you prefer to install Eclipse yourself you should use the
|
|
https://projects.eclipse.org/projects/tools.buildship[Buildship] Eclipse plugin. If you
|
|
don't already have Buildship installed it is available from the "`Eclipse marketplace`".
|
|
|
|
Spring Boot includes project specific source formatting settings, in order to have these
|
|
work with Buildship, we provide an additional Eclipse plugin that you can install:
|
|
|
|
|
|
|
|
===== Install the Spring Formatter plugin
|
|
* Select "`Help`" -> "`Install New Software`".
|
|
* Add `https://dl.bintray.com/spring/javaformat-eclipse/` as a site.
|
|
* Install "Spring Java Format".
|
|
|
|
NOTE: The plugin is 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
|
|
`Gradle -> Existing Gradle project` from the `File -> Import…` menu to import the code.
|
|
|
|
|
|
|
|
=== Importing into IntelliJ IDEA
|
|
If you have performed a checkout of this repository already, use "`File`" -> "`Open`" and
|
|
then select the root `build.gradle` file to import the code.
|
|
|
|
Alternatively, you can let IntellIJ IDEA checkout the code for you. Use "`File`" ->
|
|
"`New`" -> "`Project from Version Control`" and
|
|
`https://github.com/spring-projects/spring-boot` for the URL. Once the checkout has
|
|
completed, a pop-up will suggest to open the project.
|
|
|
|
|
|
|
|
==== Install the Spring Formatter plugin
|
|
If you haven't done so, install the formatter plugin so that proper formatting rules are
|
|
applied automatically when you reformat code in the IDE.
|
|
|
|
* Download the latest https://search.maven.org/search?q=g:io.spring.javaformat%20AND%20a:spring-javaformat-intellij-plugin[IntelliJ IDEA plugin].
|
|
* Select "`IntelliJ IDEA`" -> "`Preferences`".
|
|
* Select "`Plugins`".
|
|
* Select the wheel and "`Install Plugin from Disk...`".
|
|
* Select the jar file you've downloaded.
|
|
|
|
|
|
|
|
==== Import additional code style
|
|
The formatter does not cover all rules (such as order of imports) and an additional file
|
|
needs to be added.
|
|
|
|
* Select "`IntelliJ IDEA`" -> "`Preferences`".
|
|
* Select "`Editor`" -> "`Code Style`".
|
|
* Select the wheel and "`Import Scheme`" -> "`IntelliJ IDEA code style XML`".
|
|
* Select `idea/codeStyleConfig.xml` from this repository.
|
|
|
|
|
|
|
|
=== Importing into Other IDEs
|
|
Gradle is well supported by most Java IDEs. Refer to your vendor documentation.
|
|
|
|
|
|
|
|
== Cloning the git repository on Windows
|
|
Some files in the git repository may exceed the Windows maximum file path (260
|
|
characters), depending on where you clone the repository. If you get `Filename too long`
|
|
errors, set the `core.longPaths=true` git option:
|
|
|
|
```
|
|
git clone -c core.longPaths=true https://github.com/spring-projects/spring-boot
|
|
```
|