diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 00000000..48f0e968 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,154 @@ += Contributing to Spring Security + +First off, thank you for taking the time to contribute! :+1: :tada: + +== Table of Contents + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[[code-of-conduct]] +== Code of Conduct + +This project is governed by the https://github.com/spring-projects/.github/blob/main/CODE_OF_CONDUCT.md[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-to-contribute]] +== How to Contribute + +[[ask-questions]] +=== Ask Questions + +If you have a question, check Stack Overflow using +https://stackoverflow.com/questions/tagged/spring-security+or+spring-ldap+or+spring-authorization-server+or+spring-session?tab=Newest[this list of tags]. +Find an existing discussion, or start a new one if necessary. + +If you believe there is an issue, search through https://github.com/spring-projects/spring-ldap/issues[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. + +[[find-an-issue]] +=== Find an Existing Issue + +There are issues in Spring LDAP with the labels https://github.com/spring-projects/spring-ldap/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+ideal-for-contribution%22[`ideal-for-contribution`] or https://github.com/spring-projects/spring-ldap/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 <>. +You can volunteer by commenting on these tickets, and we will assign them to you. + +[[create-an-issue]] +=== Create an Issue + +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 <> 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 https://github.com/spring-projects/spring-ldap/issues[GitHub]. + +Many issues are caused by subtle behavior, typos, and unintended configuration. +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. + +We love contributors, and we may ask you to <>. + +[[issue-lifecycle]] +=== Issue Lifecycle + +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 https://spring.io/projects/spring-ldap#support[the earliest supported branch] where <>. + +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. + +[[build-from-source]] +=== Build from Source + +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. + +[[code-style]] +=== Source Code Style + +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. + +To format the code as well as check the style, run `./gradlew format check`. + +[[submit-a-pull-request]] +=== Submit a Pull Request + +We are excited for your pull request! :heart: + +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. + +[[sign-cla]] +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 https://spring.io/blog/2025/01/06/hello-dco-goodbye-cla-simplifying-contributions-to-spring[Hello DCO, Goodbye CLA: Simplifying Contributions to Spring]. + [[create-an-issue]] +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. + 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. + [[choose-a-branch]] +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). + If there is no milestone, choose `main`. + Once merged, the fix will be forwarded-ported to applicable branches including `main`. + [[create-a-local-branch]] +1. Create a local branch + If this is for an issue, consider a branch name with the issue number, like `gh-22276`. + [[write-tests]] +1. Add documentation and JUnit Tests for your changes. + [[update-copyright]] +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. + [[add-since]] +1. If on `main`, add `@since` JavaDoc attributes to new public APIs that your PR adds + [[change-rnc]] +1. If you are updating the XSD, please instead update the RNC file and then run `./gradlew :spring-security-config:rncToXsd`. + [[format-code]] +1. For each commit, build the code using `./gradlew format check`. + This command ensures the code meets most of <>; a notable exception is import order. + [[commit-atomically]] +1. Choose the granularity of your commits consciously and squash commits that represent + multiple edits or corrections of the same logical change. + 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. + [[format-commit-messages]] +1. 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 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. + Present tense is preferred. ++ +[indent=0] +---- +Address NullPointerException + +Closes gh-22276 +---- +[[reference-issue]] +1. If there is a prior issue, reference the GitHub issue number in the description of the pull request. ++ +[indent=0] +---- +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 + +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 Spring Security. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 49c1eab6..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,288 +0,0 @@ -_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 team when evaluating your submission._ - -_Please refer back to this document as a checklist before issuing any pull -request; this will save time for everyone!_ - -## Code of Conduct -This project adheres to the Contributor Covenant [code of conduct](CODE_OF_CONDUCT.adoc). -By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. - -## Understand the basics - -Not sure what a pull request is, or how to submit one? Take a look at GitHub's -excellent [help documentation][] first. - - -## Search JIRA first; create an issue if necessary - -Is there already an issue that addresses your concern? Do a bit of searching -in our [JIRA issue tracker][] to see if you can find something similar. If not, -please create a new issue before submitting a pull request unless the change is -truly trivial, e.g. typo fixes, removing compiler warnings, etc. - -## Discuss non-trivial contribution ideas with committers - -If you're considering anything more than correcting a typo or fixing a minor -bug, please discuss it on the [JIRA issue tracker][] 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 mailing -list for prior discussions. - -## Create your branch from `main` - -If your pull request addresses a bug or improvement, please create your branch -from Spring LDAP's `main` branch. Rest assured that if your pull -request is accepted, these changes will also eventually -be merged into any other branches we feel appropriate. - - -## Use short branch names - -Branches used when submitting pull requests should preferably be named -according to JIRA issues, e.g. 'LDAP-1234'. Otherwise, use succinct, lower-case, -dash (-) delimited names, such as 'fix-warnings', 'fix-typo', etc. In -[fork-and-edit][] cases, the GitHub default 'patch-1' is fine as well. 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. - - -## Mind the whitespace - -Please carefully follow the whitespace and formatting conventions already -present in the framework. - -1. Tabs, not spaces -1. Unix (LF), not DOS (CRLF) line endings -1. Eliminate all trailing whitespace -1. Wrap Javadoc at 90 characters -1. Aim to wrap code at 90 characters, but favor readability over wrapping -1. Preserve existing formatting; i.e. do not reformat code for its own sake -1. Search the codebase using `git grep` and other tools to discover common - naming conventions, etc. -1. Latin-1 (ISO-8859-1) encoding for Java sources; use `native2ascii` to convert - if necessary - - -## Add Apache license header to all new classes - -```java -/* - * Copyright 2002-2013 the original author or authors. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * https://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package ...; -``` - -## Update Apache license header to modified files as necessary - -Always check the date range in the license header. For example, if you've -modified a file in 2013 whose header still reads - -```java - * Copyright 2002-2011 the original author or authors. -``` - -then be sure to update it to 2013 appropriately - -```java - * Copyright 2002-2013 the original author or authors. -``` - -## Use @since tags for newly-added public API types and methods - -e.g. - -```java -/** - * ... - * - * @author First Last - * @since 1.3 - * @see ... - */ -``` - -## Submit JUnit test cases for all behavior changes - -Search the codebase to find related unit tests and add additional @Test methods -within. It is also acceptable to submit test cases on a per JIRA issue basis, -e.g. - -```java -package org.springframework.beans.factory.support; - -/** - * Unit tests for SPR-8954, in which a custom {@link InstantiationAwareBeanPostProcessor} - * forces the predicted type of a FactoryBean, effectively preventing retrieval of the - * bean from calls to #getBeansOfType(FactoryBean.class). The implementation of - * {@link AbstractBeanFactory#isFactoryBean(String, RootBeanDefinition)} now ensures - * that not only the predicted bean type is considered, but also the original bean - * definition's beanClass. - * - * @author Chris Beams - */ -public class Spr8954Tests { - - @Test - public void cornerSpr8954() { - // ... - } -} -``` - - -## Squash commits - -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 many resources online to help you understand how these tools work. -Here is one: https://book.git-scm.com/4_interactive_rebasing.html. - - -## Use real name in git commits - -Please configure git to use your real first and last name for any commits you -intend to submit as pull requests. For example, this is not acceptable: - - Author: Nickname - -Rather, please include your first and last name, properly capitalized, as -submitted against the SpringSource contributor license agreement: - - Author: First Last - -This helps ensure traceability against the CLA, and also goes a long way to -ensuring useful output from tools like `git shortlog` and others. - -You can configure this globally via the account admin area GitHub (useful for -fork-and-edit cases); globally with - - git config --global user.name "First Last" - git config --global user.email user@mail.com - -or locally for the spring-framework repository only by omitting the '--global' -flag: - - cd spring-framework - git config user.name "First Last" - git config user.email user@mail.com - - -## Format commit messages - -Please read and follow the [commit guidelines section of Pro Git][]. - -Most importantly, please format your commit messages in the following way -(adapted from the commit template in the link above): - - Short (50 chars or less) summary of changes - - More detailed explanatory text, if necessary. Wrap it to about 72 - characters or so. In some contexts, the first line is treated as the - subject of an email and the rest of the text as the body. The blank - line separating the summary from the body is critical (unless you omit - the body entirely); tools like rebase can get confused if you run the - two together. - - Further paragraphs come after blank lines. - - - Bullet points are okay, too - - - Typically a hyphen or asterisk is used for the bullet, preceded by a - single space, with blank lines in between, but conventions vary here - - Issue: SPR-1234, SPR-1235 - - -1. Use imperative statements in the subject line, e.g. "Fix broken Javadoc link" -1. Begin the subject line sentence with a capitalized verb, e.g. "Add, Prune, - Fix, Introduce, Avoid, etc." -1. Do not end the subject line with a period -1. Keep the subject line to 50 characters or less if possible -1. Wrap lines in the body at 72 characters or less -1. Mention associated JIRA issue(s) at the end of the commit comment, prefixed - with "Issue: " as above -1. In the body of the commit message, explain how things worked before this - commit, what has changed, and how things work now - -For examples of this style, issue a `git log --author=cbeams` in the -spring-framework git repository. For convenience, here are several such commits: - -https://github.com/SpringSource/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078 -https://github.com/SpringSource/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da -https://github.com/SpringSource/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6 -https://github.com/SpringSource/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477 - -## Sign commit with a Developer Certificate of Origin - -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 https://spring.io/blog/2025/01/06/hello-dco-goodbye-cla-simplifying-contributions-to-spring[Hello DCO, Goodbye CLA: Simplifying Contributions to Spring]. - -## Run all tests prior to submission - -Please run `./gradlew build` prior to submitting any changes. - - -## Submit your pull request - -Subject line: - -Follow the same conventions for pull request subject lines as mentioned above -for commit message subject lines. - -In the body: - -1. 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. -1. Add any additional information and ask questions; start a conversation, or - continue one from JIRA -1. Mention the JIRA issue ID -1. Also mention that you have submitted the CLA as described above - -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. - - -## Mention your pull request on the associated JIRA issue - -Add a comment to the associated JIRA issue(s) linking to your new pull request. - - -## Expect discussion and rework - -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. - -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. - -[help documentation]: https://help.github.com/send-pull-requests -[JIRA issue tracker]: https://jira.springsource.org/browse/LDAP -[SpringSource CLA form]: https://support.springsource.com/spring_committer_signup -[fork-and-edit]: https://github.com/blog/844-forking-with-the-edit-button -[commit guidelines section of Pro Git]: https://progit.org/book/ch5-2.html#commit_guidelines