diff --git a/CONTRIBUTING-DOCUMENTATION.adoc b/CONTRIBUTING-DOCUMENTATION.adoc deleted file mode 100644 index 2c77b5a0e7a..00000000000 --- a/CONTRIBUTING-DOCUMENTATION.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= How to Contribute to the Reference Manual - -The Spring Framework reference manual uses http://asciidoctor.org/[asciidoctor]. This -document describes how to contribute documentation updates. - -== Building with Gradle - -You can build the documentation using Gradle using the `asciidoctor` task. For example, -from the project root execute the following command: - -[indent=0] ----- - ./gradlew asciidoctor ----- - -The generated reference manual will then be available at -`build/asciidoc/html5/index.html`. - -== Live Editing - -One of the nice features about using Asciidoctor is the support for live editing. - -You will find a Guardfile already present at -`spring-framework/src/docs/asciidoc/Guardfile`. First, follow the setup instructions -within the -http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc -with Live Preview] document. Once you have done that, there are additional gems to -install to make it work (assuming that you are using http://livereload.com/[LiveReload]): - -[indent=0] ----- - gem install guard-rspec guard-livereload ----- - -When running `guard start` within the `src/asciidoc/` folder, any changes to the -`src/asciidoc/index.adoc` file are automatically written to -`src/asciidoc/build/index.html`. - -== Troubleshooting - -* If you are using LiveReload, select _Allow access to file URLs_ in the -LiveEdit plugin options of your browser. -* The icon used to enable _LiveReload_ can be a bit confusing. The dot is empty when it -is disabled and full when the plugin is active. Make sure to enable it on the tab -displaying the `index.html` file. -* Ensure you are _not_ running `guard start` at all, as two instances could not run at -the same time. To exit a current session in a clean way, type `e` in the shell. - -== Documentation Notes - -Some notes on the documentation. - -* Documentation is wrapped at 90 chars. Ensure that you manually wrap your edits. -* Tabs are used for indentation. Do not use spaces. -* Follow the existing style when inserting `source` blocks. - -Here are some useful resources for working with Asciidoctor: - -* http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Quick Reference] -* http://asciidoctor.org/docs/user-manual/[Asciidoctor Manual] -* http://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writers Guide] diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 28d356f3a8e..abe931ad59b 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,270 +1,126 @@ -:wiki-root: https://github.com/spring-projects/spring-framework/wiki +[[contributing]] +# Contributing to the Spring Framework +:toc: preamble +:toclevels: 4 +:docinfo1: -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]] -# Code of Conduct - -This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct]. -By participating you are expected to uphold this code. Please report unacceptable behavior -to spring-code-of-conduct@pivotal.io. - -[[take-your-first-steps]] -# Take Your First Steps - -[[understand-the-basics]] -## Understand the basics - -Not sure what a pull request is, or how to submit one? Take a look at -GitHub’s excellent -https://help.github.com/categories/collaborating-on-projects-using-issues-and-pull-requests/[help documentation] -first. - -[[search-stack-overflow-first-discuss-if-necessary]] -## Search Stack Overflow first; discuss if necessary - -If you’re unsure why something isn’t working or wondering if there is a -better way of doing it please check on Stack Overflow first and if -necessary start a discussion. This is the official list of -https://spring.io/questions[Spring-related tags]. In short the issue -tracker should be used to report issues and make feature requests. - -[[search-jira-create-an-issue-if-necessary]] -## Search JIRA; create an issue if necessary - -Is there already an issue that addresses your concern? Do a bit of -searching in our https://jira.spring.io/browse/SPR[JIRA issue tracker] to see if you can find something -similar. If you do not find something similar, please create a new JIRA -issue before submitting a pull request unless the change is truly -trivial – for example: typo fixes, removing compiler warnings, etc. - -[[sign-the-contributor-license-agreement-cla]] -## Sign the Contributor License Agreement (CLA) - -If you have not previously done so, please sign the -https://cla.pivotal.io/sign/spring[Contributor License Agreement]. -If you forget to do so, you’ll be reminded when you submit a pull request. - -[[create-a-branch]] -# Create a Branch - -[[branch-from-master]] -## Branch from `master` - -Master currently represents work toward Spring Framework 5.0. Please -submit all pull requests there, even bug fixes and minor improvements. -Backports to `4.3.x` will be considered on a case-by-case basis. - -[[use-short-branch-names]] -## Use short branch names - -Branches used when submitting pull requests should preferably be named -according to JIRA issues, e.g. `SPR-1234'. Otherwise, use succinct, -lower-case, dash (-) delimited names, such as `fix-warnings', -`fix-typo', etc. In https://github.com/blog/844-forking-with-the-edit-button[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. - -[[use-spring-framework-code-style]] -# Use Spring Framework Code Style - -The complete -https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Code-Style[Spring Framework Code Style] -reference is available on the wiki. - -[[prepare-your-commit]] -# Prepare Your Commit - -[[submit-junit-test-cases-for-all-behavior-changes]] -## Submit JUnit test cases for all behavior changes - -Search the codebase to find related tests and add additional `@Test` -methods as appropriate. It is also acceptable to submit test cases on a -per JIRA issue basis, for example: - -[source,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]] -## Squash commits - -Use `git rebase --interactive --autosquash`, `git add --patch`, and -other tools to ``squash'' multiple commits into a single atomic commit. -In addition to the man pages for git, there are many resources online to -help you understand how these tools work. The -http://git-scm.com/book/en/Git-Tools-Rewriting-History[Rewriting History section of Pro Git] -provides a good overview. +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 -[[use-real-name-in-git-commits]] -## 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: +[[how-question]] +### Discuss -.... -Author: Nickname -.... +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. -Rather, please include your first and last name, properly capitalized, -as submitted against the Spring Individual Contributor License Agreement -(ICLA): +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. -.... -Author: First Last -.... -This helps ensure traceability against the ICLA and also goes a long way -to ensuring useful output from tools like `git shortlog` and others. -You can configure this via the account admin area in GitHub (useful for -fork-and-edit cases); _globally_ on your machine with +[[how-ticket]] +### Create a Ticket -.... -git config --global user.name "First Last" -git config --global user.email user@mail.com -.... +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 <>. -or _locally_ for the `spring-framework` repository only by omitting the `–global' flag: +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. -.... -cd spring-framework -git config user.name "First Last" -git config user.email user@mail.com -.... +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. -[[format-commit-messages]] -## Format commit messages -Please read and follow the -http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines[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): +[[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 <>. 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. -.... -Short (50 chars or less) summary of changes +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. -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. +1. List the JIRA issue number in the PR description. -Further paragraphs come after blank lines. +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. - - Bullet points are okay, too +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. - - 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''. -2. Begin the subject line with a capitalized verb, e.g. ``Add, Prune, -Fix, Introduce, Avoid, etc.'' -3. Do not end the subject line with a period. -4. Restrict the subject line to 50 characters or less if possible. -5. Wrap lines in the body at 72 characters or less. -6. Mention associated JIRA issue(s) at the end of the commit comment, -prefixed with ``Issue:'' as above. -7. In the body of the commit message, explain how things worked before -this commit, what has changed, and how things work now. +[[code-style]] +## Source Code Style -For examples of this style, issue a `git log --author=cbeams` in the -`spring-framework` git repository. For convenience, here are several -such commits: +* 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. -* https://github.com/spring-projects/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078 -* https://github.com/spring-projects/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da -* https://github.com/spring-projects/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6 -* https://github.com/spring-projects/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477 -[[run-the-final-checklist]] -# Run the Final Checklist -[[run-all-tests-prior-to-submission]] -## Run all tests prior to submission +[[documentation]] +## Reference Docs -See the https://github.com/spring-projects/spring-framework#building-from-source[building from source] -section of the `README` for instructions. Make sure that all tests pass prior to submitting your -pull request. +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. -[[submit-your-pull-request]] -## Submit your pull request - -Subject line: +When making changes locally, use `./gradlew asciidoctor` and then browse the result under +`build/asciidoc/html5/index.html`. -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. -2. Add any additional information and ask questions; start a -conversation or continue one from JIRA. -3. Mention the JIRA issue ID. -4. Also mention that you have submitted the ICLA 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]] -## 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]] -## 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. In other -words, you do not need to issue a new pull request when asked to make -changes. \ No newline at end of file +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`. \ No newline at end of file