Contributing to Spring Security

If you have a question, check Stack Overflow using this list of tags. Find an existing discussion, or start a new one if necessary.

If you believe there is an issue, search through existing 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.

There are many issues in Spring Security with the labels ideal-for-contribution or first-timers-only that are a great way to contribute to a discussion or to a PR. You can volunteer by commenting on these tickets, and we will assign them to you.

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 creating a ticket, please take the time to ask and research first.

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. The issue tracker is an important place of record for design discussions and should be self-sufficient.

Once you’re ready, create an issue on GitHub.

Many issues are caused by subtle behavior, typos, and unintended configuration. Creating a 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.

We love contributors, and we may ask you to submit a PR with a fix.

When an issue is first created, it is flagged waiting-for-triage waiting for a team 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 branch (or no branch if a feature) or is closed with a specific status. The target branch is the earliest supported branch where the change will be applied.

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.

See Build from Source for instructions on how to check out, build, and import the Spring Security source code into your IDE.

The wiki pages Code Style and IntelliJ IDEA Editor Settings define the source file coding standards we use along with some IDEA editor settings we customize.

To format the code as well as check the style, run ./gradlew format check.

We are excited for your pull request!

Please do your best to follow these steps. Don’t worry if you don’t get them all correct the first time, we will help you.

1. If you have not previously done so, please sign the Contributor License Agreement. You will be reminded automatically when you submit the PR.

2. Must you 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. For typos and straightforward bug fixes, starting with a pull request is encouraged. Please include a description for context and motivation. Note that the team may close your pull request if it’s not a fit for the project.

3. 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). If there is no milestone, choose main. Once merged, the fix will be forwarded-ported to applicable branches including main.

4. Create a local branch If this is for an issue, consider a branch name with the issue number, like gh-22276.

5. Add documentation and JUnit Tests for your changes.

6. In all files you edited, if the copyright header is of the form 2002-20xx, update the final copyright year to the current year.

7. If on main, add @since JavaDoc attributes to new public APIs that your PR adds

8. If you are updating the XSD, please instead update the RNC file and then run ./gradlew :spring-security-config:rncToXsd.

9. For each commit, build the code using ./gradlew format check. This command ensures the code meets most of the style guide; a notable exception is import order.

10. Choose the granularity of your commits consciously and squash commits that represent multiple edits or corrections of the same logical change. See Rewriting History section of Pro Git for an overview of streamlining the commit history.

11. Format commit messages using 55 characters for the subject line, 72 characters per line for the description, followed by the issue fixed, for example, Closes gh-22276. See the Commit Guidelines section of Pro Git for best practices around commit messages, and use git log to see some examples. Present tense is preferred.

    Address NullPointerException
    
    Closes gh-22276

12. If there is a prior issue, reference the GitHub issue number in the description of the pull request.

    Closes gh-22276

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. When it is time to merge, you’ll be asked to squash your commits.

Participate in Reviews