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.
133 lines
5.3 KiB
133 lines
5.3 KiB
[[contributing]] |
|
# Contributing to the Spring Framework |
|
|
|
First off, thank you for taking the time to contribute! |
|
|
|
**Table of Contents** |
|
|
|
* <<conduct>> |
|
* <<how>> |
|
** <<how-question>> |
|
** <<how-ticket>> |
|
** <<how-pull-request>> |
|
* <<code-style>> |
|
* <<documentation>> |
|
|
|
|
|
|
|
[[conduct]] |
|
## Code of Conduct |
|
|
|
This project is governed by the link:CODE_OF_CONDUCT.adoc[Spring Code of Conduct]. |
|
By participating you are expected to uphold this code. |
|
Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. |
|
|
|
|
|
|
|
[[how]] |
|
## How to Contribute |
|
|
|
|
|
[[how-question]] |
|
### Discuss |
|
|
|
If you have a question, check StackOverflow using |
|
https://spring.io/questions[this list of tags], organized by Spring project. |
|
Find an existing discussion or start a new one if necessary. |
|
|
|
If you suspect an issue, perform a search in the |
|
https://jira.spring.io/browse/SPR[JIRA issue tracker], using a few different keywords. |
|
When you find related issues and discussions, prior or current, it helps you to learn and |
|
it helps us to make a decision. |
|
|
|
|
|
|
|
[[how-ticket]] |
|
### Create a Ticket |
|
|
|
Reporting an issue or making a feature request is a great way to contribute. Your feedback |
|
and the conversations that result from it provide a continuous flow of ideas. However, |
|
before you do that, please take the time to <<how-question,research first>>. |
|
|
|
When an issue is first created, it may not be assigned and will not have a fix version. |
|
Within a day or two, the issue is assigned to a specific committer and the target |
|
version is set to "Waiting for Triage". The committer will then review the issue, ask for |
|
further information if needed, and based on the findings, the issue is either assigned a fix |
|
version or rejected. |
|
|
|
When a fix is ready, the issue is marked "Resolved" and may still be re-opened. Once a fix |
|
is released, the issue is permanently "Closed". If necessary, you will need to create a new, |
|
related ticket with a fresh description. |
|
|
|
|
|
|
|
[[how-pull-request]] |
|
### Submit a Pull Request |
|
|
|
You can contribute a source code change by submitting a pull request. |
|
|
|
1. If you have not previously done so, please sign the |
|
https://cla.pivotal.io/sign/spring[Contributor License Agreement]. You will also be reminded |
|
automatically when you submit a pull request. |
|
|
|
1. For all but the most trivial of contributions, please <<how-ticket>>. The purpose of the |
|
ticket is to understand and discuss the underlying issue or feature. We use the JIRA issue tracker |
|
as the preferred place of record for conversations and conclusions. In that sense discussions |
|
directly under a PR are more implementation detail oriented and transient in nature. |
|
|
|
1. Always check out the `master` branch and submit pull requests against it |
|
(for target version see link:settings.gradle[settings.gradle]). |
|
Backports to prior versions will be considered on a case-by-case basis and reflected as |
|
the fix version in the issue tracker. |
|
|
|
1. Use short branch names, preferably based on the JIRA issue (e.g. `SPR-1234`), or |
|
otherwise using succinct, lower-case, dash (-) delimited names, such as `fix-warnings'. |
|
|
|
1. Choose the granularity of your commits consciously and squash commits that represent |
|
multiple edits or corrections of the same logical change. See |
|
http://git-scm.com/book/en/Git-Tools-Rewriting-History[Rewriting History section of Pro Git] |
|
for an overview of streamlining commit history. |
|
|
|
1. Format commit messages using 55 characters for the subject line, 72 lines for the |
|
description, followed by related issues, e.g. `Issues: SPR-1234, SPR-1235`. |
|
See the |
|
http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines[Commit Guidelines section of Pro Git] |
|
for best practices around commit messages and use `git log` to see some examples. |
|
|
|
1. List the JIRA issue number in the PR description. |
|
|
|
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. |
|
|
|
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. |
|
|
|
|
|
|
|
[[code-style]] |
|
## Source Code Style |
|
|
|
* The https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Code-Style[Spring Framework Code Style] |
|
wiki page defines the the coding standards used for Spring Framework source files. |
|
* The https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-IDEA-Code-Formatting[IDEA Code Formatting] |
|
wiki page describes changes we make to the default code formatting settings in Intellij IDEA. |
|
|
|
|
|
|
|
[[documentation]] |
|
## Reference Docs |
|
|
|
The reference documentation is in the `src/docs/asciidoc` directory and, in |
|
http://asciidoctor.org/[Asciidoctor] format. For trivial changes, you may be able to browse, |
|
edit source files, and submit directly from Github. |
|
|
|
When making changes locally, use `./gradlew asciidoctor` and then browse the result under |
|
`build/asciidoc/html5/index.html`. |
|
|
|
Asciidoctor also supports live editing. For more details read |
|
http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview]. |
|
Note that if you choose the |
|
http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/#using-a-system-monitor[System Monitor] |
|
option, you can find a Guardfile under `src/docs/asciidoc`.
|
|
|