From e30d1d92ec943208b6647efe69e6f224e3a7ae22 Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Tue, 24 Oct 2017 22:54:26 -0400 Subject: [PATCH] Overhaul contributing guidelines The guidelines were originally created several years ago. This commit does not fundamentally change anything but rather make the guidance more compact. The commit consolidates into into CONTRIBUTING.adoc information from CONTRIBUTING-DOCUMENTATION.adoc and also the wiki page "The Lifecycle of an Issue". --- CONTRIBUTING-DOCUMENTATION.adoc | 61 ------- CONTRIBUTING.adoc | 312 +++++++++----------------------- 2 files changed, 84 insertions(+), 289 deletions(-) delete mode 100644 CONTRIBUTING-DOCUMENTATION.adoc diff --git a/CONTRIBUTING-DOCUMENTATION.adoc b/CONTRIBUTING-DOCUMENTATION.adoc deleted file mode 100644 index 2c77b5a0e7..0000000000 --- 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 28d356f3a8..abe931ad59 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. +First off, thank you for taking the time to contribute! -_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. +[[conduct]] +## Code of Conduct -[[take-your-first-steps]] -# Take Your First Steps +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. -[[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 +[[how]] +## How to Contribute -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 +[[how-question]] +### Discuss -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. +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. -[[sign-the-contributor-license-agreement-cla]] -## Sign the Contributor License Agreement (CLA) +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. -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` +[[how-ticket]] +### Create a Ticket -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. +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 <>. -[[use-short-branch-names]] -## Use short branch names +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. -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. +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. -[[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 +[[how-pull-request]] +### Submit a Pull Request -[[submit-junit-test-cases-for-all-behavior-changes]] -## Submit JUnit test cases for all behavior changes +You can contribute a source code change by submitting a pull request. -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: +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. -[source,java] ----- -package org.springframework.beans.factory.support; +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. -/** - * 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 { +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. - @Test - public void cornerSpr8954() { - // ... - } -} ----- +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'. -[[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 +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] -provides a good overview. +for an overview of streamlining commit history. -[[use-real-name-in-git-commits]] -## Use real name in git commits +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. -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: +1. List the JIRA issue number in the PR description. -.... -Author: Nickname -.... +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. -Rather, please include your first and last name, properly capitalized, -as submitted against the Spring Individual Contributor License Agreement -(ICLA): +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. -.... -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 +[[code-style]] +## Source Code Style -.... -git config --global user.name "First Last" -git config --global user.email user@mail.com -.... +* 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. -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]] -## Format commit messages +[[documentation]] +## Reference Docs -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]. +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. -Most importantly, please format your commit messages in the following -way (adapted from the commit template in the link above): +When making changes locally, use `./gradlew asciidoctor` and then browse the result under +`build/asciidoc/html5/index.html`. -.... -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''. -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. - -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/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 - -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. - -[[submit-your-pull-request]] -## 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. -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