From 5ac377499cb5d5c51e3d1faa16ea9ab3417aa75d Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Wed, 25 Oct 2017 10:05:41 -0400 Subject: [PATCH] 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. --- CONTRIBUTING.adoc => CONTRIBUTING.md | 94 +++++++++-------------- README.md | 107 +++++++++++++++------------ 2 files changed, 96 insertions(+), 105 deletions(-) rename CONTRIBUTING.adoc => CONTRIBUTING.md (56%) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.md similarity index 56% rename from CONTRIBUTING.adoc rename to CONTRIBUTING.md index 1df09e5d7c92..b78f3ebab8ca 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.md @@ -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* -* <> -* <> -** <> -** <> -** <> -* <> -* <> +* [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 spring-code-of-conduct@pivotal.io. +### 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 <>. +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 <>. 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`. diff --git a/README.md b/README.md index f626d3f52835..d31901ec29cf 100644 --- a/README.md +++ b/README.md @@ -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 spring-code-of-conduct@pivotal.io. -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 git@github.com:spring-projects/spring-framework.git` +Start by checking out the sources: +``` +git clone git@github.com: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).