forked from spring-projects/spring-framework
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
CONTRIBUTING is markdwon again + polish README
The main way CONTRIBUTING will be viewed is on Github and the output is just not good enough to justify using asciidoctor vs md/txt as the recommended on the Github help page for contributing guidelines. For example it was attractive to use a TOC and that works on Github but doesn't look good. In the end it's a very short TOC and maintaining manually is easy enough and it's easier to control the look.
- Loading branch information
1 parent
bf4c97c
commit 5ac3774
Showing
2 changed files
with
96 additions
and
105 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,53 +1,41 @@ | ||
| [[contributing]] | ||
| # Contributing to the Spring Framework | ||
| ## Contributing to the Spring Framework | ||
|
|
||
| First off, thank you for taking the time to contribute! | ||
|
|
||
| **Table of Contents** | ||
| *Table of Contents* | ||
|
|
||
| * <<conduct>> | ||
| * <<how>> | ||
| ** <<how-question>> | ||
| ** <<how-ticket>> | ||
| ** <<how-pull-request>> | ||
| * <<code-style>> | ||
| * <<documentation>> | ||
| * [Code of Conduct](#Code-of-Conduct) | ||
| * [How to Contribute](#How-to-Contribute) | ||
| * [Discuss](#Discuss) | ||
| * [Create a Ticket](#Create-a-Ticket) | ||
| * [Submit a Pull Request](#Submit-a-Pull-Request) | ||
| * [Source Code Style](#Source-Code-Style) | ||
| * [Reference Docs](#Reference-Docs) | ||
|
|
||
| ### Code of Conduct | ||
|
|
||
| [[conduct]] | ||
| ## Code of Conduct | ||
|
|
||
| This project is governed by the link:CODE_OF_CONDUCT.adoc[Spring Code of Conduct]. | ||
| This project is governed by the [Spring Code of Conduct](CODE_OF_CONDUCT.adoc). | ||
| By participating you are expected to uphold this code. | ||
| Please report unacceptable behavior to [email protected]. | ||
|
|
||
| ### How to Contribute | ||
|
|
||
|
|
||
| [[how]] | ||
| ## How to Contribute | ||
|
|
||
|
|
||
| [[how-question]] | ||
| ### Discuss | ||
| #### Discuss | ||
|
|
||
| If you have a question, check StackOverflow using | ||
| https://spring.io/questions[this list of tags], organized by Spring project. | ||
| [this list of tags](https://spring.io/questions), organized by Spring project. | ||
| Find an existing discussion or start a new one if necessary. | ||
|
|
||
| If you suspect an issue, perform a search in the | ||
| https://jira.spring.io/browse/SPR[JIRA issue tracker], using a few different keywords. | ||
| [JIRA issue tracker](https://jira.spring.io/browse/SPR), 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. | ||
|
|
||
|
|
||
|
|
||
| [[how-ticket]] | ||
| ### Create a Ticket | ||
| #### Create a Ticket | ||
|
|
||
| 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 <<how-question,research first>>. | ||
| before you do that, please take the time to [research first](#Discuss). | ||
|
|
||
| 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 | ||
|
|
@@ -59,24 +47,22 @@ When a fix is ready, the issue is marked "Resolved" and may still be re-opened. | |
| is released, the issue is permanently "Closed". If necessary, you will need to create a new, | ||
| related ticket with a fresh description. | ||
|
|
||
|
|
||
|
|
||
| [[how-pull-request]] | ||
| ### Submit a 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 | ||
| [Contributor License Agreement](https://cla.pivotal.io/sign/spring). You will also be reminded | ||
| automatically when you submit a pull request. | ||
|
|
||
| 1. For all but the most trivial of contributions, please <<how-ticket>>. 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. For all but the most trivial of contributions, please [create a ticket](#Create-a-Ticket). | ||
| 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]). | ||
| (for target version see [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. | ||
|
|
||
|
|
@@ -85,13 +71,13 @@ otherwise using succinct, lower-case, dash (-) delimited names, such as `fix-war | |
|
|
||
| 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] | ||
| [Rewriting History section of Pro Git](http://git-scm.com/book/en/Git-Tools-Rewriting-History) | ||
| for an overview of streamlining commit history. | ||
|
|
||
| 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] | ||
| [Commit Guidelines section of Pro Git](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines) | ||
| for best practices around commit messages and use `git log` to see some examples. | ||
|
|
||
| 1. List the JIRA issue number in the PR description. | ||
|
|
@@ -104,30 +90,24 @@ If asked to make corrections, simply push the changes against the same branch, a | |
| pull request will be updated. In other words, you do not need to create a new pull request | ||
| when asked to make changes. | ||
|
|
||
| ### Source Code Style | ||
|
|
||
| The wiki page | ||
| [Spring Framework Code Style](https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Code-Style) | ||
| defines the source file coding standards we use while the [IDEA formatting](https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-IDEA-Code-Formatting) | ||
| page describes the changes we make to the default code formatting settings in IntelliJ IDEA. | ||
|
|
||
| [[code-style]] | ||
| ## Source Code Style | ||
|
|
||
| * 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. | ||
| [[documentation]] | ||
| ## Reference Docs | ||
| ### Reference Docs | ||
|
|
||
| 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, | ||
| The reference documentation is in the [src/docs/asciidoc](src/docs/asciidoc) directory and, in | ||
| [Asciidoctor](http://asciidoctor.org/) format. For trivial changes, you may be able to browse, | ||
| edit source files, and submit directly from Github. | ||
|
|
||
| When making changes locally, use `./gradlew asciidoctor` and then browse the result under | ||
| `build/asciidoc/html5/index.html`. | ||
|
|
||
| Asciidoctor also supports live editing. For more details read | ||
| http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview]. | ||
| [Editing AsciiDoc with Live Preview](http://asciidoctor.org/docs/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] | ||
| [System Monitor](http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/#using-a-system-monitor) | ||
| option, you can find a Guardfile under `src/docs/asciidoc`. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,70 +1,81 @@ | ||
| Please read the | ||
| This is the home of the Spring Framework that underlies all | ||
| [Spring projects](https://spring.io/projects). Collectively the Spring Framework and the | ||
| family of related Spring projects make up what we call "Spring". | ||
|
|
||
| Spring provides everything you need beyond the Java language to create enterprise | ||
| applications in a wide range of scenarios and architectures. Please read the | ||
| [Overview](https://docs.spring.io/spring/docs/current/spring-framework-reference/overview.html#spring-introduction) | ||
| in the reference documentation for a quick introduction. | ||
| section in the reference for a more complete introduction. | ||
|
|
||
| ## Code of Conduct | ||
|
|
||
| This project is governed by the [Spring Code of Conduct](CODE_OF_CONDUCT.adoc). | ||
| By participating you are expected to uphold this code. | ||
| Please report unacceptable behavior to [email protected]. | ||
|
|
||
| For Maven repository information see [downloading Spring artifacts][], or if unable to | ||
| use Maven or other transitive dependency management tools, see | ||
| [building a distribution with dependencies][]. | ||
| ## Artifacts | ||
|
|
||
| For Maven repository information see | ||
| [downloading Spring artifacts](https://github.com/spring-projects/spring-framework/wiki/Downloading-Spring-artifacts), | ||
| or if unable to use Maven or other transitive dependency management tools, see | ||
| [building a distribution with dependencies](https://github.com/spring-projects/spring-framework/wiki/Building-a-distribution-with-dependencies). | ||
|
|
||
| Documentation is available in the form of [reference docs][], [Javadoc][], and Github Wiki pages. | ||
| ## Learn | ||
|
|
||
| For contributing see the [contributor guidelines][] for details. | ||
| The Spring Frameworks maintains | ||
| [reference documentation](http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/), | ||
| Github [wiki pages](https://github.com/spring-projects/spring-framework/wiki), and an | ||
| [API reference](http://docs.spring.io/spring-framework/docs/current/javadoc-api/). | ||
|
|
||
| ## Building from Source | ||
| The Spring Framework uses a [Gradle][]-based build system. In the instructions | ||
| below, [`./gradlew`][] is invoked from the root of the source tree and serves as | ||
| a cross-platform, self-contained bootstrap mechanism for the build. | ||
| You can find guides and tutorials on [https://spring.io](https://spring.io/guides). | ||
|
|
||
| ### Prerequisites | ||
| ## Build from Source | ||
|
|
||
| [Git][] and [JDK 8 update 20 or later][JDK8 build] | ||
| The Spring Framework uses a [Gradle](http://gradle.org) build. In the instructions below, | ||
| the [Gradle Wrapper](http://vimeo.com/34436402) is invoked from the root of the source | ||
| tree and serves as a cross-platform, self-contained bootstrap mechanism for the build. | ||
|
|
||
| To build you will need [Git](http://help.github.com/set-up-git-redirect) and | ||
| [JDK 8 update 20 or later](http://www.oracle.com/technetwork/java/javase/downloads). | ||
| Be sure that your `JAVA_HOME` environment variable points to the `jdk1.8.0` folder | ||
| extracted from the JDK download. | ||
|
|
||
| ### Check out sources | ||
| `git clone [email protected]:spring-projects/spring-framework.git` | ||
| Start by checking out the sources: | ||
| ``` | ||
| git clone [email protected]:spring-projects/spring-framework.git | ||
| ``` | ||
|
|
||
| ### Import sources into your IDE | ||
| Run `./import-into-eclipse.sh` or read `import-into-idea.md` as appropriate. | ||
| > **Note:** Per the prerequisites above, ensure that you have JDK 8 configured properly in your IDE. | ||
| To import into an IDE, ensure JDK 8 is configured. Then run `./import-into-eclipse.sh` | ||
| or read [import-into-idea.md](import-into-idea.md). For IntelliJ please do read the | ||
| instructions as a straight-up import will not work. | ||
|
|
||
| ### Install all spring-\* jars into your local Maven cache | ||
| `./gradlew install` | ||
| To compile, test, build all jars, distribution zips, and docs use: | ||
| ``` | ||
| ./gradlew build | ||
| ``` | ||
|
|
||
| ### Compile and test; build all jars, distribution zips, and docs | ||
| `./gradlew build` | ||
| To install all spring-\* jars into your local Maven cache: | ||
| ``` | ||
| ./gradlew install | ||
| ``` | ||
|
|
||
| ... and discover more commands with `./gradlew tasks`. See also the [Gradle | ||
| build and release FAQ][]. | ||
| Discover more commands: | ||
| ``` | ||
| ./gradlew tasks | ||
| ``` | ||
|
|
||
| ## Staying in Touch | ||
| Follow [@SpringCentral][] as well as [@SpringFramework][] and its [team members][] | ||
| on Twitter. In-depth articles can be found at [The Spring Blog][], and releases | ||
| are announced via our [news feed][]. | ||
| See also [CONTRIBUTING](CONTRIBUTING.md) and the | ||
| [Gradle build and release FAQ](https://github.com/spring-projects/spring-framework/wiki/Gradle-build-and-release-FAQ). | ||
|
|
||
| ## Stay in Touch | ||
|
|
||
| Follow [@SpringCentral](https://twitter.com/springcentral), | ||
| [@SpringFramework](https://twitter.com/springframework), and its | ||
| [team members](https://twitter.com/springframework/lists/team/members) on Twitter. | ||
| In-depth articles can be found at [The Spring Blog](http://spring.io/blog/), | ||
| and releases are announced via our [news feed](http://spring.io/blog/category/news). | ||
|
|
||
| ## License | ||
| The Spring Framework is released under version 2.0 of the [Apache License][]. | ||
|
|
||
| [downloading Spring artifacts]: https://github.com/spring-projects/spring-framework/wiki/Downloading-Spring-artifacts | ||
| [building a distribution with dependencies]: https://github.com/spring-projects/spring-framework/wiki/Building-a-distribution-with-dependencies | ||
| [Javadoc]: http://docs.spring.io/spring-framework/docs/current/javadoc-api/ | ||
| [reference docs]: http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/ | ||
| [Spring Framework JIRA]: https://jira.spring.io/browse/SPR | ||
| [Gradle]: http://gradle.org | ||
| [`./gradlew`]: http://vimeo.com/34436402 | ||
| [Git]: http://help.github.com/set-up-git-redirect | ||
| [JDK8 build]: http://www.oracle.com/technetwork/java/javase/downloads | ||
| [Gradle build and release FAQ]: https://github.com/spring-projects/spring-framework/wiki/Gradle-build-and-release-FAQ | ||
| [Pull requests]: https://help.github.com/categories/collaborating-on-projects-using-issues-and-pull-requests/ | ||
| [contributor guidelines]: https://github.com/spring-projects/spring-framework/blob/master/CONTRIBUTING.adoc | ||
| [@SpringFramework]: https://twitter.com/springframework | ||
| [@SpringCentral]: https://twitter.com/springcentral | ||
| [team members]: https://twitter.com/springframework/lists/team/members | ||
| [The Spring Blog]: http://spring.io/blog/ | ||
| [news feed]: http://spring.io/blog/category/news | ||
| [Apache License]: http://www.apache.org/licenses/LICENSE-2.0 | ||
|
|
||
| The Spring Framework is released under version 2.0 of the | ||
| [Apache License](http://www.apache.org/licenses/LICENSE-2.0). |