2017-10-27 09:20:45 +08:00
# Contributing to the Spring Framework
2017-10-25 03:57:47 +08:00
2017-10-25 22:13:11 +08:00
First off, thank you for taking the time to contribute! :+1: :tada:
2017-10-25 10:54:26 +08:00
2017-10-27 09:20:45 +08:00
### Table of Contents
2017-10-25 11:28:13 +08:00
2017-10-25 23:19:30 +08:00
* [Code of Conduct ](#code-of-conduct )
* [How to Contribute ](#how-to-contribute )
2021-10-08 17:08:38 +08:00
* [Ask questions ](#ask-questions )
2019-11-26 23:56:37 +08:00
* [Create an Issue ](#create-an-issue )
* [Issue Lifecycle ](#issue-lifecycle )
2017-10-25 23:19:30 +08:00
* [Submit a Pull Request ](#submit-a-pull-request )
* [Build from Source ](#build-from-source )
* [Source Code Style ](#source-code-style )
* [Reference Docs ](#reference-docs )
2017-10-25 11:28:13 +08:00
2017-10-25 22:05:41 +08:00
### Code of Conduct
2017-10-25 10:54:26 +08:00
2025-01-01 17:08:18 +08:00
This project is governed by the [Spring Code of Conduct ](https://github.com/spring-projects/spring-framework#coc-ov-file ).
2017-10-25 10:54:26 +08:00
By participating you are expected to uphold this code.
2024-06-10 17:46:27 +08:00
Please report unacceptable behavior to spring-code-of-conduct@spring.io.
2017-10-25 10:54:26 +08:00
2017-10-25 22:05:41 +08:00
### How to Contribute
2017-10-25 10:54:26 +08:00
2021-10-08 17:08:38 +08:00
#### Ask questions
2017-10-25 03:57:47 +08:00
2019-11-05 22:27:46 +08:00
If you have a question, check Stack Overflow using
2021-10-08 17:08:38 +08:00
[this list of tags ](https://stackoverflow.com/questions/tagged/spring+or+spring-mvc+or+spring-aop+or+spring-jdbc+or+spring-transactions+or+spring-annotations+or+spring-jms+or+spring-el+or+spring-test+or+spring+or+spring-remoting+or+spring-orm+or+spring-jmx+or+spring-cache+or+spring-webflux?tab=Newest ). Find an existing discussion, or start a new one if necessary.
2017-10-25 03:57:47 +08:00
2019-11-26 23:56:37 +08:00
If you believe there is an issue, search through
[existing issues ](https://github.com/spring-projects/spring-framework/issues ) trying a
few different ways to find discussions, past or current, that are related to the issue.
Reading those discussions helps you to learn about the issue, and helps us to make a
decision.
2019-11-25 12:35:19 +08:00
2017-10-25 03:57:47 +08:00
2019-11-26 23:56:37 +08:00
#### Create an Issue
2017-10-25 03:57:47 +08:00
2017-10-25 10:54:26 +08:00
Reporting an issue or making a feature request is a great way to contribute. Your feedback
2019-11-26 23:56:37 +08:00
and the conversations that result from it provide a continuous flow of ideas. However,
2021-10-08 17:08:38 +08:00
before creating a ticket, please take the time to [ask and research ](#ask-questions ) first.
2018-01-29 22:25:46 +08:00
2021-10-08 20:00:23 +08:00
If you create an issue after a discussion on Stack Overflow, please provide a description
2019-11-26 23:56:37 +08:00
in the issue instead of simply referring to Stack Overflow. The issue tracker is an
important place of record for design discussions and should be self-sufficient.
2018-01-29 22:25:46 +08:00
2021-10-08 17:08:38 +08:00
Once you're ready, create an issue on [GitHub ](https://github.com/spring-projects/spring-framework/issues ).
2021-10-08 20:00:23 +08:00
Many issues are caused by subtle behavior, typos, and unintended configuration.
2021-10-08 17:08:38 +08:00
Creating a [Minimal Reproducible Example ](https://stackoverflow.com/help/minimal-reproducible-example )
(starting with https://start.spring.io for example) of the problem helps the team
2021-10-08 20:00:23 +08:00
quickly triage your issue and get to the core of the problem.
2018-01-29 22:25:46 +08:00
2019-11-26 23:56:37 +08:00
#### Issue Lifecycle
2017-10-25 03:57:47 +08:00
2019-05-05 15:13:09 +08:00
When an issue is first created, it is flagged `waiting-for-triage` waiting for a team
2019-11-26 23:56:37 +08:00
member to triage it. Once the issue has been reviewed, the team may ask for further
information if needed, and based on the findings, the issue is either assigned a target
milestone or is closed with a specific status.
2019-05-05 15:13:09 +08:00
2019-11-26 23:56:37 +08:00
When a fix is ready, the issue is closed and may still be re-opened until the fix is
released. After that the issue will typically no longer be reopened. In rare cases if the
issue was not at all fixed, the issue may be re-opened. In most cases however any
follow-up reports will need to be created as new issues with a fresh description.
2017-10-25 03:57:47 +08:00
2017-10-25 22:05:41 +08:00
#### Submit a Pull Request
2017-10-25 10:54:26 +08:00
2019-11-26 23:56:37 +08:00
1. Should you create an issue first? No, just create the pull request and use the
description to provide context and motivation, as you would for an issue. If you want
to start a discussion first or have already created an issue, once a pull request is
created, we will close the issue as superseded by the pull request, and the discussion
about the issue will continue under the pull request.
2017-10-25 10:54:26 +08:00
2021-06-11 18:38:42 +08:00
1. Always check out the `main` branch and submit pull requests against it
2017-10-25 22:05:41 +08:00
(for target version see [settings.gradle ](settings.gradle )).
2017-10-25 10:54:26 +08:00
Backports to prior versions will be considered on a case-by-case basis and reflected as
the fix version in the issue tracker.
1. Choose the granularity of your commits consciously and squash commits that represent
multiple edits or corrections of the same logical change. See
2019-03-21 06:48:14 +08:00
[Rewriting History section of Pro Git ](https://git-scm.com/book/en/Git-Tools-Rewriting-History )
2019-11-05 22:27:46 +08:00
for an overview of streamlining the commit history.
2017-10-25 03:57:47 +08:00
2025-01-07 16:55:36 +08:00
1. All commits must include a _Signed-off-by_ trailer at the end of each commit message
to indicate that the contributor agrees to the Developer Certificate of Origin.
For additional details, please refer to the blog post
[Hello DCO, Goodbye CLA: Simplifying Contributions to Spring ](https://spring.io/blog/2025/01/06/hello-dco-goodbye-cla-simplifying-contributions-to-spring ).
2019-05-05 15:08:21 +08:00
1. Format commit messages using 55 characters for the subject line, 72 characters per line
2024-09-26 20:03:46 +08:00
for the description, followed by the issue fixed, for example, `Closes gh-22276` . See the
2019-03-21 06:48:14 +08:00
[Commit Guidelines section of Pro Git ](https://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines )
2019-11-05 22:27:46 +08:00
for best practices around commit messages, and use `git log` to see some examples.
2017-10-25 03:57:47 +08:00
2019-11-26 23:56:37 +08:00
1. If there is a prior issue, reference the GitHub issue number in the description of the
pull request.
2017-10-25 03:57:47 +08:00
2017-10-25 10:54:26 +08:00
If accepted, your contribution may be heavily modified as needed prior to merging.
You will likely retain author attribution for your Git commits granted that the bulk of
your changes remain intact. You may also be asked to rework the submission.
2017-10-25 03:57:47 +08:00
2017-10-25 10:54:26 +08:00
If asked to make corrections, simply push the changes against the same branch, and your
pull request will be updated. In other words, you do not need to create a new pull request
when asked to make changes.
2017-10-25 03:57:47 +08:00
2019-08-26 23:45:01 +08:00
#### Participate in Reviews
Helping to review pull requests is another great way to contribute. Your feedback
can help to shape the implementation of new features. When reviewing pull requests,
however, please refrain from approving or rejecting a PR unless you are a core
committer for the Spring Framework.
2017-10-25 23:14:00 +08:00
### Build from Source
See the [Build from Source ](https://github.com/spring-projects/spring-framework/wiki/Build-from-Source )
wiki page for instructions on how to check out, build, and import the Spring Framework
source code into your IDE.
2017-10-25 22:05:41 +08:00
### Source Code Style
2017-10-25 03:57:47 +08:00
2017-10-28 04:02:54 +08:00
The wiki pages
[Code Style ](https://github.com/spring-projects/spring-framework/wiki/Code-Style ) and
[IntelliJ IDEA Editor Settings ](https://github.com/spring-projects/spring-framework/wiki/IntelliJ-IDEA-Editor-Settings )
2019-11-05 22:27:46 +08:00
define the source file coding standards we use along with some IDEA editor settings we customize.
2017-10-25 03:57:47 +08:00
2017-10-25 22:05:41 +08:00
### Reference Docs
2017-10-25 03:57:47 +08:00
2023-07-07 17:18:43 +08:00
The reference documentation is authored in [Asciidoctor ](https://asciidoctor.org/ ) format
using [Antora ](https://docs.antora.org/antora/latest/ ). The source files for the documentation
reside in the [framework-docs/modules/ROOT ](framework-docs/modules/ROOT ) directory. For
trivial changes, you may be able to browse, edit source files, and submit directly from GitHub.
2017-10-25 03:57:47 +08:00
2023-07-07 17:18:43 +08:00
When making changes locally, execute `./gradlew antora` and then browse the results under
`framework-docs/build/site/index.html` .
2017-10-25 03:57:47 +08:00
2021-02-17 01:28:19 +08:00
Asciidoctor also supports live editing. For more details see
[AsciiDoc Tooling ](https://docs.asciidoctor.org/asciidoctor/latest/tooling/ ).
