Skip to content

Fixes in documentation #9099

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 12, 2020
Merged

Fixes in documentation #9099

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
30e60c2
Rework CONTRIBUTING.adoc
mluppi Oct 6, 2020
b015486
Rework community.adoc
mluppi Oct 6, 2020
9b6f519
Apply minor rewording and formatting
mluppi Oct 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 102 additions & 47 deletions CONTRIBUTING.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,27 @@ _Please refer back to this document as a checklist before issuing any pull reque

= Code of Conduct

Please see our https://github.com/spring-projects/.github/blob/master/CODE_OF_CONDUCT.md[code of conduct]
Please see our https://github.com/spring-projects/.github/blob/master/CODE_OF_CONDUCT.md[code of conduct].

= Similar but different

Each Spring module is slightly different than 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.
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.

= Importing into IDE

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.

* IDE Setup
* Install Spring Tool Suite 3.6.0+
* You will need the following plugins installed (can be found on the Extensions Page)
* Gradle Eclipse
* Groovy Eclipse
** Install Spring Tool Suite 3.6.0+
** You will need the following plugins installed (can be found on the Extensions Page)
*** Gradle Eclipse
*** Groovy Eclipse
* Importing the project into Spring Tool Suite
* File->Import…->Gradle Project
** File -> Import… -> Gradle Project

As of new versions of Spring Tool Suite, you might need to install Groovy Eclipse pointing directly to the updates plugin location. To install Groovy Eclipse on Spring Tool Suite based on Eclipse Oxigen you must do the following steps:
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:

Help->Install New Software…->Add the following URL into _Work with_ field:
Help -> Install New Software… -> Add the following URL into _Work with_ field:
https://dist.springsource.org/snapshot/GRECLIPSE/e4.7/[https://dist.springsource.org/snapshot/GRECLIPSE/e4.7/]

= Understand the basics
Expand All @@ -33,78 +33,101 @@ Not sure what a pull request is, or how to submit one? Take a look at GitHub's e

= Search GitHub issues; create an issue if necessary

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.
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.

= 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 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.

= Sign the Contributor License Agreement

If you have not previously done so, please fill out and
submit the https://cla.pivotal.io/sign/spring[Contributor License Agreement].
If you have not previously done so, please fill out and submit the https://cla.pivotal.io/sign/spring[Contributor License Agreement].

= Create your branch from master

Create your topic branch to be submitted as a pull request from master. The Spring team will consider your pull request for backporting on a case-by-case basis; you don't need to worry about submitting anything for backporting.

= Use short branch names

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', 'fix-typo', etc. 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.
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.

= Keep commits focused

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.

= Mind the whitespace

Please carefully follow the whitespace and formatting conventions already present in the framework.
Please carefully follow the whitespace and formatting conventions already present in the framework.

. Tabs, not spaces
. Unix (LF), not dos (CRLF) line endings
. Eliminate all trailing whitespace
. Aim to wrap code at 120 characters, but favor readability over wrapping
. Preserve existing formatting; i.e. do not reformat code for its own sake
. Search the codebase using git grep and other tools to discover common naming conventions, etc.
. Search the codebase using `git grep` and other tools to discover common naming conventions, etc.
. UTF-8 encoding for Java sources and XML files

Whitespace management tips

. 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.
. Use git's pre-commit.sample hook to prevent invalid whitespace from being pushed out. You can enable it by moving ~/spring-security/.git/hooks/pre-commit.sample to ~/spring-security/.git/hooks/pre-commit and ensuring it is executable. For more information on hooks refer to https://git-scm.com/book/cs/ch7-3.html[Pro Git's Pre-Commit Hook's section]
. 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].

= Add Apache license header to all new classes

----
/*
* Copyright 2002-2020 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 2012 whose header still reads
<pre>
* Copyright 2002-2011 the original author or authors.
</pre>
then be sure to update it to 2012 appropriately
<pre>
Always check the date range in the license header. For example, if you've modified a file in 2020 whose header still reads

----
* Copyright 2002-2012 the original author or authors.
</pre>
----

then be sure to update it to the current year appropriately (e.g. 2020)

----
* Copyright 2002-2020 the original author or authors.
----

= Use @since tags for newly-added public API types and methods

e.g.
<pre>
Example:

----
/**
* …
*
* @author First Last
* @since 3.2
* @since 5.4
* @see …
*/
</pre>
----

= Submit JUnit test cases for all behavior changes

Search the codebase to find related unit tests and add additional `@Test` methods within.
Search the codebase to find related unit tests and add additional `@Test` methods within.

. 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`.
. 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.
. 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`.
. 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`.

= Update spring-security-x.y.rnc for schema changes

Expand All @@ -114,44 +137,76 @@ Changes to the XML schema will be overwritten by the Gradle build task.

= 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[https://book.git-scm.com/4_interactive_rebasing.html].
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.

= 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:
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]:

----
First Last <[email protected]>
----

Rather, please include your first and last name, properly capitalized, as submitted against the SpringSource contributor license agreement:
<pre>
Author: First Last &lt;link:mailto:&#x75;&#115;&#101;&#114;&#64;&#109;&#x61;&#x69;&#108;&#46;&#99;&#111;&#x6d;&#38;&#103;&#116;[&#x75;&#115;&#101;&#114;&#64;&#109;&#x61;&#x69;&#108;&#46;&#99;&#111;&#x6d;&#38;&#103;&#116;];
</pre>
This helps ensure traceability against the CLA, and also goes a long way to ensuring useful output from tools like git shortlog and others.
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
You can configure this globally:

or locally for the spring-security repository only by omitting the '–global' flag:
<pre>
cd spring-security
----
git config --global user.name "First Last"
git config --global user.email [email protected]
----

or locally for the current repository by omitting the `--global` flag:

----
git config user.name "First Last"
git config user.email link:mailto:&#x75;&#115;&#101;&#x72;&#64;&#x6d;&#x61;&#x69;&#x6c;&#46;&#x63;&#111;&#109;[&#x75;&#115;&#101;&#x72;&#64;&#x6d;&#x61;&#x69;&#x6c;&#46;&#x63;&#111;&#109;]
</pre>
git config user.email [email protected]
----

= Format commit messages

. Keep the subject line to 50 characters or less if possible
. Do not end the subject line with a period
. In the body of the commit message, explain how things worked before this commit, what has changed, and how things work now
. Include Closes gh-<issue-number> at the end if this fixes a GitHub issue
. Include `Closes gh-<issue-number>` at the end if this fixes a GitHub issue
. Avoid markdown, including back-ticks identifying code

Example:

----
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

Closes gh-123
----


= Run all tests prior to submission

----
./gradlew clean build integrationTest
----

= Submit your pull request

Subject line:
*Subject line:*

Follow the same conventions for pull request subject lines as mentioned above for commit message subject lines.

In the body:
*In the body:*

. 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
. Add any additional information and ask questions; start a conversation, or continue one from GitHub Issues
Expand All @@ -167,4 +222,4 @@ Add a comment to the associated GitHub issue(s) linking to your new pull request

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.
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.
4 changes: 2 additions & 2 deletions docs/manual/src/docs/asciidoc/_includes/about/community.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ The following are some of the best ways to get help:
[[community-becoming-involved]]
== Becoming Involved
We welcome your involvement in the Spring Security project.
There are many ways to contribute, including answering questions on StackOverflow, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, reporting bugs, or simply making suggestions.
For more information, see our https://github.com/spring-projects/spring-security/blob/master/CONTRIBUTING.md[Contributing] documentation.
There are many ways to contribute, including answering questions on Stack Overflow, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, reporting bugs, or simply making suggestions.
For more information, see our https://github.com/spring-projects/spring-security/blob/master/CONTRIBUTING.adoc[Contributing] documentation.

[[community-source]]
== Source Code
Expand Down