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.
This commit is contained in:
Rossen Stoyanchev
parent
bf4c97cb1c
commit
5ac377499c
|
|
@ -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 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 <<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
|
||||
### Reference Docs
|
||||
|
||||
* 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
|
||||
|
||||
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`.
|
||||
105
README.md
105
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
|
||||
|
||||
Documentation is available in the form of [reference docs][], [Javadoc][], and Github Wiki pages.
|
||||
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).
|
||||
|
||||
For contributing see the [contributor guidelines][] for details.
|
||||
## Learn
|
||||
|
||||
## 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.
|
||||
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/).
|
||||
|
||||
### Prerequisites
|
||||
You can find guides and tutorials on [https://spring.io](https://spring.io/guides).
|
||||
|
||||
[Git][] and [JDK 8 update 20 or later][JDK8 build]
|
||||
## Build from Source
|
||||
|
||||
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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue