Skip to content

Commit 94826d4

Browse files
jzheauxjzheaux
committed
Revisit Contribution Guidelines
Closes gh-12925 Closes gh-6094
1 parent f0ef540 commit 94826d4

File tree

1 file changed

+129
-207
lines changed

1 file changed

+129
-207
lines changed

‎CONTRIBUTING.adoc

Lines changed: 129 additions & 207 deletions
Original file line numberDiff line numberDiff line change
@@ -1,232 +1,154 @@
1-
_Have something you'd like to contribute to the framework? We welcome pull requests, but ask that you carefully read this document first to understand how best to submit them; what kind of changes are likely to be accepted; and what to expect from the Spring Security team when evaluating your submission._
1+
= Contributing to Spring Security
22

3-
_Please refer back to this document as a checklist before issuing any pull request; this will save time for everyone!_
3+
First off, thank you for taking the time to contribute! :+1: :tada:
44

5-
= Code of Conduct
5+
== Table of Contents
66

7-
Please see our https://github.com/spring-projects/.github/blob/main/CODE_OF_CONDUCT.md[code of conduct].
7+
* <<code-of-conduct>>
8+
* <<how-to-contribute>>
9+
* <<ask-questions>>
10+
* <<find-an-issue>>
11+
* <<create-an-issue>>
12+
* <<issue-lifecycle>>
13+
* <<submit-a-pull-request>>
14+
* <<build-from-source>>
15+
* <<code-style>>
816

9-
= Similar but different
17+
[[code-of-conduct]]
18+
== Code of Conduct
1019

11-
Each Spring module is slightly different from one another in terms of team size, number of issues, etc. Therefore, each project is managed slightly different. You will notice that this document is very similar to the https://github.com/spring-projects/spring-framework/wiki/Contributor-guidelines[Spring Framework Contributor guidelines]. However, there are some subtle differences between the two documents, so please be sure to read this document thoroughly.
20+
This project is governed by the https://github.com/spring-projects/.github/blob/main/CODE_OF_CONDUCT.md[Spring code of conduct].
21+
By participating you are expected to uphold this code.
22+
Please report unacceptable behavior to [email protected].
23+
24+
[[how-to-contribute]]
25+
== How to Contribute
26+
27+
[[ask-questions]]
28+
=== Ask Questions
29+
30+
If you have a question, check Stack Overflow using
31+
https://stackoverflow.com/questions/tagged/spring-security+or+spring-ldap+or+spring-authorization-server+or+spring-session?tab=Newest[this list of tags].
32+
Find an existing discussion, or start a new one if necessary.
33+
34+
If you believe there is an issue, search through https://github.com/spring-projects/spring-security/issues[existing issues] trying a few different ways to find discussions, past or current, that are related to the issue.
35+
Reading those discussions helps you to learn about the issue, and helps us to make a decision.
36+
37+
[[find-an-issue]]
38+
=== Find an Existing Issue
39+
40+
There are many issues in Spring Security with the labels https://github.com/spring-projects/spring-security/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+ideal-for-contribution%22[`ideal-for-contribution`] or https://github.com/spring-projects/spring-security/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+first-timers-only%22[`first-timers-only`] that are a great way to contribute to a discussion or <<submit-a-pull-request,to a PR>>.
41+
You can volunteer by commenting on these tickets, and we will assign them to you.
1242

13-
= Importing into IDE
43+
[[create-an-issue]]
44+
=== Create an Issue
1445

15-
The following provides information on setting up a development environment that can run the sample in https://www.springsource.org/sts[Spring Tool Suite 3.6.0+]. Other IDE's should work using Gradle's IDE support, but have not been tested.
46+
Reporting an issue or making a feature request is a great way to contribute.
47+
Your feedback and the conversations that result from it provide a continuous flow of ideas.
48+
However, before creating a ticket, please take the time to <<ask-questions,ask and research>> first.
1649

17-
* IDE Setup
18-
** Install Spring Tool Suite 3.6.0+
19-
** You will need the following plugins installed (can be found on the Extensions Page)
20-
*** Gradle Eclipse
21-
*** Groovy Eclipse
22-
* Importing the project into Spring Tool Suite
23-
** File -> Import… -> Gradle Project
50+
If you create an issue after a discussion on Stack Overflow, please provide a description in the issue instead of simply referring to Stack Overflow.
51+
The issue tracker is an important place of record for design discussions and should be self-sufficient.
2452

25-
As of new versions of Spring Tool Suite, you might need to install Groovy Eclipse pointing directly to the updated plugin location. To install Groovy Eclipse on Spring Tool Suite based on Eclipse Oxigen you must do the following steps:
53+
Once you're ready, create an issue on https://github.com/spring-projects/spring-security/issues[GitHub].
2654

27-
Help -> Install New Software… -> Add the following URL into _Work with_ field:
28-
https://dist.springsource.org/snapshot/GRECLIPSE/e4.7/[https://dist.springsource.org/snapshot/GRECLIPSE/e4.7/]
55+
Many issues are caused by subtle behavior, typos, and unintended configuration.
56+
Creating a https://stackoverflow.com/help/minimal-reproducible-example[Minimal Reproducible Example] (starting with https://start.spring.io for example) of the problem helps the team quickly triage your issue and get to the core of the problem.
2957

30-
= Understand the basics
58+
We love contributors, and we may ask you to <<submit-a-pull-request,submit a PR with a fix>>.
3159

32-
Not sure what a pull request is, or how to submit one? Take a look at GitHub's excellent https://help.github.com/articles/using-pull-requests[help documentation first].
60+
[[issue-lifecycle]]
61+
=== Issue Lifecycle
3362

34-
= Search GitHub issues; create an issue if necessary
63+
When an issue is first created, it is flagged `waiting-for-triage` waiting for a team member to triage it.
64+
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 branch (or no branch if a feature) or is closed with a specific status.
65+
The target branch is https://spring.io/projects/spring-security#support[the earliest supported branch] where <<choose-a-branch,the change will be applied>>.
3566

36-
Is there already an issue that addresses your concern? Do a bit of searching in our https://github.com/spring-projects/spring-security/issues[GitHub issues] to see if you can find something similar. If not, please create a new issue before submitting a pull request unless the change is not a user facing issue.
67+
When a fix is ready, the issue is closed and may still be re-opened until the fix is released.
68+
After that the issue will typically no longer be reopened.
69+
In rare cases if the issue was not at all fixed, the issue may be re-opened.
70+
In most cases however any follow-up reports will need to be created as new issues with a fresh description.
3771

38-
= Discuss non-trivial contribution ideas with committers
72+
[[build-from-source]]
73+
=== Build from Source
3974

40-
If you're considering anything more than correcting a typo or fixing a minor bug, please discuss it on the https://gitter.im/spring-projects/spring-security[Spring Security Gitter] before submitting a pull request. We're happy to provide guidance but please spend an hour or two researching the subject on your own including searching the forums for prior discussions.
75+
See https://github.com/spring-projects/spring-security/tree/main#building-from-source[Build from Source] for instructions on how to check out, build, and import the Spring Security source code into your IDE.
4176

42-
= Sign the Contributor License Agreement
77+
[[code-style]]
78+
=== Source Code Style
4379

44-
If you have not previously done so, please fill out and submit the https://cla.pivotal.io/sign/spring[Contributor License Agreement].
80+
The wiki pages https://github.com/spring-projects/spring-framework/wiki/Code-Style[Code Style] and https://github.com/spring-projects/spring-framework/wiki/IntelliJ-IDEA-Editor-Settings[IntelliJ IDEA Editor Settings] define the source file coding standards we use along with some IDEA editor settings we customize.
4581

46-
= Create your branch from oldest maintenance branch
82+
To format the code as well as check the style, run `./gradle format check`.
4783

48-
Create your topic branch to be submitted as a pull request from the oldest impacted and supported maintenance branch.
49-
You can find the supported versions by looking at the https://github.com/spring-projects/spring-security/milestones[milestones page].
50-
Switch to a branch named `<major>.<minor>.x` from the smallest milestone in the format of `<major>.<minor>.<patch>(-<prerelease>)`.
51-
The spring team will ensure the code gets merged forward into additional branches.
84+
[[submit-a-pull-request]]
85+
=== Submit a Pull Request
5286

53-
= Use short branch names
87+
We are excited for your pull request! :heart:
5488

55-
Branches used when submitting pull requests should preferably be named according to GitHub issues, e.g. `gh-1234` or `gh-1234-fix-npe`. Otherwise, use succinct, lower-case, dash (`-`) delimited names, such as `fix-warnings` or `fix-typo`. This is important, because branch names show up in the merge commits that result from accepting pull requests, and should be as expressive and concise as possible.
56-
57-
= Keep commits focused
58-
59-
Remember each ticket should be focused on a single item of interest since the tickets are used to produce the changelog. Since each commit should be tied to a single GitHub issue, ensure that your commits are focused. For example, do not include an update to a transitive library in your commit unless the GitHub is to update the library. Reviewing your commits is essential before sending a pull request.
60-
61-
= Mind the whitespace
62-
63-
Please carefully follow the whitespace and formatting conventions already present in the framework.
64-
65-
. Tabs, not spaces
66-
. Unix (LF), not dos (CRLF) line endings
67-
. Eliminate all trailing whitespace
68-
. Aim to wrap code at 120 characters, but favor readability over wrapping
69-
. Preserve existing formatting; i.e. do not reformat code for its own sake
70-
. Search the codebase using `git grep` and other tools to discover common naming conventions, etc.
71-
. UTF-8 encoding for Java sources and XML files
72-
73-
Whitespace management tips
74-
75-
. You can use the https://marketplace.eclipse.org/content/anyedit-tools[AnyEdit Eclipse plugin] to ensure spaces are used and to clean up trailing whitespaces.
76-
. Use Git's `pre-commit.sample` hook to prevent invalid whitespace from being pushed out. You can enable it by moving `.git/hooks/pre-commit.sample` to `.git/hooks/pre-commit` and ensuring it is executable. For more information on hooks refer to https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks].
77-
78-
= Add Apache license header to all new classes
89+
Please do your best to follow these steps.
90+
Don't worry if you don't get them all correct the first time, we will help you.
7991

92+
[[sign-cla]]
93+
1. If you have not previously done so, please sign the https://cla.spring.io/sign/spring[Contributor License Agreement].
94+
You will be reminded automatically when you submit the PR.
95+
[[create-an-issue]]
96+
1. Must you https://github.com/spring-projects/spring-security/issues/new/choose[create an issue] first? No, but it is recommended for features and larger bug fixes. It's easier discuss with the team first to determine the right fix or enhancement.
97+
For typos and straightforward bug fixes, starting with a pull request is encouraged.
98+
Please include a description for context and motivation.
99+
Note that the team may close your pull request if it's not a fit for the project.
100+
[[choose-a-branch]]
101+
1. Always check out the branch indicated in the milestone and submit pull requests against it (for example, for milestone `5.8.3` use the `5.8.x` branch).
102+
If there is no milestone, choose `main`.
103+
Once merged, the fix will be forwarded-ported to applicable branches including `main`.
104+
[[create-a-local-branch]]
105+
1. Create a local branch
106+
If this is for an issue, consider a branch name with the issue number, like `gh-22276`.
107+
[[write-tests]]
108+
1. Add JUnit Tests for your changes
109+
[[update-copyright]]
110+
1. In all files you edited, if the copyright header is of the form 2002-20xx, update the final copyright year to the current year.
111+
[[add-since]]
112+
1. If on `main`, add `@since` JavaDoc attributes to new public APIs that your PR adds
113+
[[change-rnc]]
114+
1. If you are updating the XSD, please instead update the RNC file and then run `./gradlew :spring-security-config:rncToXsd`.
115+
[[format-code]]
116+
1. For each commit, build the code using `./gradlew format check`.
117+
This command ensures the code meets most of <<code-style,the style guide>>; a notable exception is import order.
118+
[[commit-atomically]]
119+
1. Choose the granularity of your commits consciously and squash commits that represent
120+
multiple edits or corrections of the same logical change.
121+
See https://git-scm.com/book/en/Git-Tools-Rewriting-History[Rewriting History section of Pro Git] for an overview of streamlining the commit history.
122+
[[format-commit-messages]]
123+
1. Format commit messages using 55 characters for the subject line, 72 characters per line
124+
for the description, followed by the issue fixed, for example, `Closes gh-22276`.
125+
See the https://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.
126+
Present tense is preferred.
127+
+
128+
[indent=0]
80129
----
81-
/*
82-
* Copyright 2002-2020 the original author or authors.
83-
*
84-
* Licensed under the Apache License, Version 2.0 (the "License");
85-
* you may not use this file except in compliance with the License.
86-
* You may obtain a copy of the License at
87-
*
88-
* https://www.apache.org/licenses/LICENSE-2.0
89-
*
90-
* Unless required by applicable law or agreed to in writing, software
91-
* distributed under the License is distributed on an "AS IS" BASIS,
92-
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
93-
* See the License for the specific language governing permissions and
94-
* limitations under the License.
95-
*/
96-
97-
package ...;
98-
----
99-
100-
= Update Apache license header to modified files as necessary
101-
102-
Always check the date range in the license header. For example, if you've modified a file in 2020 whose header still reads
103-
104-
----
105-
* Copyright 2002-2012 the original author or authors.
106-
----
107-
108-
then be sure to update it to the current year appropriately (e.g. 2020)
109-
110-
----
111-
* Copyright 2002-2020 the original author or authors.
112-
----
113-
114-
= Use @since tags for newly-added public API types and methods
115-
116-
Example:
117-
118-
----
119-
/**
120-
* …
121-
*
122-
* @author First Last
123-
* @since 5.4
124-
* @see …
125-
*/
126-
----
127-
128-
= Submit JUnit test cases for all behavior changes
129-
130-
Search the codebase to find related unit tests and add additional `@Test` methods within.
131-
132-
. Any new tests should end in the name `Tests` (note this is plural). For example, a valid name would be `FilterChainProxyTests`. An invalid name would be `FilterChainProxyTest`.
133-
. New test methods should not start with test. This is an old JUnit3 convention and is not necessary since the method is annotated with `@Test`.
134-
135-
= Update spring-security-x.y.rnc for schema changes
136-
137-
Update the https://www.relaxng.org[RELAX NG] schema `spring-security-x.y.rnc` instead of `spring-security-x.y.xsd` if you contribute changes to supported XML configuration. The XML schema file can be generated the following Gradle task:
138-
139-
----
140-
./gradlew :spring-security-config:rncToXsd
141-
----
142-
143-
Changes to the XML schema will be overwritten by the Gradle build task.
144-
145-
= Squash commits
146-
147-
Use `git rebase --interactive`, `git add --patch` and other tools to "squash" multiple commits into atomic changes. In addition to the man pages for `git`, there are https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History[many resources online] to help you understand how these tools work.
148-
149-
= Use real name in git commits
150-
151-
Please configure Git to use your real first and last name for any commits you intend to submit as pull requests. Make sure the name is properly capitalized as submitted to the https://cla.pivotal.io[Pivotal Contributor License Agreement]:
152-
130+
Address NullPointerException
131+
132+
Closes gh-22276
153133
----
154-
First Last <[email protected]>
155-
----
156-
157-
This helps ensure traceability against the CLA, and also goes a long way to ensuring useful output from tools like Git shortlog and others.
158-
159-
You can configure this globally:
160-
161-
----
162-
git config --global user.name "First Last"
163-
git config --global user.email [email protected]
164-
----
165-
166-
or locally for the current repository by omitting the `--global` flag:
167-
168-
----
169-
git config user.name "First Last"
170-
git config user.email [email protected]
171-
----
172-
173-
= Format commit messages
174-
175-
. Keep the subject line to 50 characters or less if possible
176-
. Do not end the subject line with a period
177-
. In the body of the commit message, explain how things worked before this commit, what has changed, and how things work now
178-
. Include `Closes gh-<issue-number>` at the end if this fixes a GitHub issue
179-
. Avoid markdown, including back-ticks identifying code
180-
181-
Example:
182-
183-
----
184-
Short (50 chars or less) summary of changes
185-
186-
More detailed explanatory text, if necessary. Wrap it to about 72
187-
characters or so. In some contexts, the first line is treated as the
188-
subject of an email and the rest of the text as the body. The blank
189-
line separating the summary from the body is critical (unless you omit
190-
the body entirely); tools like rebase can get confused if you run the
191-
two together.
192-
193-
Further paragraphs come after blank lines.
194-
195-
- Bullet points are okay, too
196-
197-
- Typically a hyphen or asterisk is used for the bullet, preceded by a
198-
single space, with blank lines in between, but conventions vary here
199-
200-
Closes gh-123
201-
----
202-
203-
204-
= Run all tests prior to submission
205-
206-
----
207-
./gradlew clean build integrationTest
208-
----
209-
210-
= Submit your pull request
211-
212-
*Subject line:*
213-
214-
Follow the same conventions for pull request subject lines as mentioned above for commit message subject lines.
215-
216-
*In the body:*
217-
218-
. Explain your use case. What led you to submit this change? Why were existing mechanisms in the framework insufficient? Make a case that this is a general-purpose problem and that yours is a general-purpose solution, etc
219-
. Add any additional information and ask questions; start a conversation, or continue one from GitHub Issues
220-
. Mention any GitHub Issues
221-
. Also mention that you have submitted the CLA as described above
222-
Note that for pull requests containing a single commit, GitHub will default the subject line and body of the pull request to match the subject line and body of the commit message. This is fine, but please also include the items above in the body of the request.
223-
224-
= Mention your pull request on the associated GitHub issue
225-
226-
Add a comment to the associated GitHub issue(s) linking to your new pull request.
227-
228-
= Expect discussion and rework
229-
230-
The Spring team takes a very conservative approach to accepting contributions to the framework. This is to keep code quality and stability as high as possible, and to keep complexity at a minimum. Your changes, if accepted, may be heavily modified prior to merging. You will retain "Author:" attribution for your Git commits granted that the bulk of your changes remain intact. You may be asked to rework the submission for style (as explained above) and/or substance. Again, we strongly recommend discussing any serious submissions with the Spring Framework team prior to engaging in serious development work.
231-
232-
Note that you can always force push (`git push -f`) reworked / rebased commits against the branch used to submit your pull request. i.e. you do not need to issue a new pull request when asked to make changes.
134+
[[reference-issue]]
135+
1. If there is a prior issue, reference the GitHub issue number in the description of the pull request.
136+
+
137+
[indent=0]
138+
----
139+
Closes gh-22276
140+
----
141+
142+
If accepted, your contribution may be heavily modified as needed prior to merging.
143+
You will likely retain author attribution for your Git commits granted that the bulk of your changes remain intact.
144+
You may also be asked to rework the submission.
145+
146+
If asked to make corrections, simply push the changes against the same branch, and your pull request will be updated.
147+
In other words, you do not need to create a new pull request when asked to make changes.
148+
When it is time to merge, you'll be asked to squash your commits.
149+
150+
==== Participate in Reviews
151+
152+
Helping to review pull requests is another great way to contribute.
153+
Your feedback can help to shape the implementation of new features.
154+
When reviewing pull requests, however, please refrain from approving or rejecting a PR unless you are a core committer for Spring Security.

0 commit comments

Comments
 (0)