126 lines
5.2 KiB
Plaintext
126 lines
5.2 KiB
Plaintext
[[contributing]]
|
|
# Contributing to the Spring Framework
|
|
:toc: preamble
|
|
:toclevels: 4
|
|
|
|
First off, thank you for taking the time to contribute!
|
|
|
|
|
|
|
|
[[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`.
|