From d108db8a797cac08ab49da1ea7842d14016d8b2b Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Fri, 28 Feb 2014 15:40:13 +0100 Subject: [PATCH] Polish CONTRIBUTING page --- CONTRIBUTING.md | 101 ++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 50 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0dad727fc..9d12c52c85 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,32 +1,33 @@ _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 +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!_ -## Take your first steps +## Take Your First Steps ### Understand the basics -Not sure what a pull request is, or how to submit one? Take a look at GitHub's +Not sure what a pull request is, or how to submit one? Take a look at GitHub's excellent [help documentation][] first. ### Search JIRA first; create an issue if necessary -Is there already an issue that addresses your concern? Do a bit of searching -in our [JIRA issue tracker][] to see if you can find something similar. If not, -please create a new issue before submitting a pull request unless the change is -truly trivial, e.g. typo fixes, removing compiler warnings, etc. +Is there already an issue that addresses your concern? Do a bit of searching +in our [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. ### Discuss non-trivial contribution ideas with committers If you're considering anything more than correcting a typo or fixing a minor bug, please discuss it on the [spring-framework-contrib][] mailing list before submitting a pull request. We're happy to provide guidance, but please spend an -hour or two researching the subject on your own including searching the mailing +hour or two researching the subject on your own, including searching the mailing list for prior discussions. ### Sign the Contributor License Agreement @@ -44,11 +45,11 @@ your pull request: I have signed and agree to the terms of the SpringSource Individual Contributor License Agreement. -You do not need to include your token/id. Please add the statement above to all +You do not need to include your token/id. Please add the above statement to all future pull requests as well, simply so that the Spring Framework team knows immediately that this process is complete. -## Create a branch +## Create a Branch ### Branch from `master` @@ -64,12 +65,12 @@ according to JIRA issues, e.g. 'SPR-1234'. Otherwise, use succinct, lower-case, dash (-) delimited names, such as 'fix-warnings', 'fix-typo', etc. In [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. +accepting pull requests and should be as expressive and concise as possible. -## Use Spring code style +## Use Spring Code Style -The complete [Spring Code Style][] reference is available on the wiki. -Here's a quick summary: +The complete [Spring Code Style][] reference is available on the wiki, but +here's a quick summary: ### Mind the whitespace @@ -83,16 +84,16 @@ present in the framework. 1. Aim to wrap code at 90 characters, but favor readability over wrapping 1. Preserve existing formatting; i.e. do not reformat code for its own sake 1. Search the codebase using `git grep` and other tools to discover common - naming conventions, etc. + naming conventions, etc. 1. Latin-1 (ISO-8859-1) encoding for Java sources; use `native2ascii` to convert - if necessary + if necessary ### Add Apache license header to all new classes ```java /* - * Copyright 2002-2013 the original author or authors. + * Copyright 2002-2014 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -110,24 +111,24 @@ present in the framework. package ...; ``` -### Update Apache license header to modified files as necessary +### Update Apache license header in modified files as necessary Always check the date range in the license header. For example, if you've -modified a file in 2013 whose header still reads +modified a file in 2014 whose header still reads: ```java * Copyright 2002-2011 the original author or authors. ``` -then be sure to update it to 2013 appropriately +Then be sure to update it to 2014 accordingly: ```java - * Copyright 2002-2013 the original author or authors. + * Copyright 2002-2014 the original author or authors. ``` ### Use @since tags for newly-added public API types and methods -e.g. +For example: ```java /** @@ -139,13 +140,13 @@ e.g. */ ``` -## Prepare your commit +## Prepare Your Commit ### Submit JUnit test cases for all behavior changes -Search the codebase to find related unit tests and add additional @Test methods -within. It is also acceptable to submit test cases on a per JIRA issue basis, -e.g. +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: ```java package org.springframework.beans.factory.support; @@ -172,10 +173,10 @@ public class Spr8954Tests { ### Squash commits -Use `git rebase --interactive`, `git add --patch` and other tools to "squash" -multiple commits into atomic changes. In addition to the man pages for git, -there are many resources online to help you understand how these tools work. -Here is one: http://book.git-scm.com/4_interactive_rebasing.html. +Use `git rebase --interactive --autosquash`, `git add --patch` and other tools +to "squash" multiple commits into atomic changes. In addition to the man pages +for git, there are many resources online to help you understand how these tools +work. Here is one: http://book.git-scm.com/4_interactive_rebasing.html. ### Use real name in git commits @@ -190,17 +191,17 @@ submitted against the SpringSource contributor license agreement: Author: First Last -This helps ensure traceability against the CLA, and also goes a long way to +This helps ensure traceability against the CLA and also goes a long way to ensuring useful output from tools like `git shortlog` and others. -You can configure this globally via the account admin area GitHub (useful for -fork-and-edit cases); globally with +You can configure this via the account admin area in GitHub (useful for +fork-and-edit cases); _globally_ on your machine with git config --global user.name "First Last" git config --global user.email user@mail.com -or locally for the spring-framework repository only by omitting the '--global' -flag: +or _locally_ for the `spring-framework` repository only by omitting the +'--global' flag: cd spring-framework git config user.name "First Last" @@ -234,29 +235,29 @@ Most importantly, please format your commit messages in the following way 1. Use imperative statements in the subject line, e.g. "Fix broken Javadoc link" -1. Begin the subject line sentence with a capitalized verb, e.g. "Add, Prune, - Fix, Introduce, Avoid, etc." +1. Begin the subject line with a capitalized verb, e.g. "Add, Prune, Fix, + Introduce, Avoid, etc." 1. Do not end the subject line with a period -1. Keep the subject line to 50 characters or less if possible +1. Restrict the subject line to 50 characters or less if possible 1. Wrap lines in the body at 72 characters or less 1. Mention associated JIRA issue(s) at the end of the commit comment, prefixed - with "Issue: " as above + with "Issue: " as above 1. In the body of the commit message, explain how things worked before this - commit, what has changed, and how things work now + 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: +`spring-framework` git repository. For convenience, here are several such commits: -https://github.com/SpringSource/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078 -https://github.com/SpringSource/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da -https://github.com/SpringSource/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6 -https://github.com/SpringSource/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477 +- https://github.com/SpringSource/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078 +- https://github.com/SpringSource/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da +- https://github.com/SpringSource/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6 +- https://github.com/SpringSource/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477 -## Run the final checklist +## Run the Final Checklist ### Run all tests prior to submission -See the [building from source][] section of the README for instructions. Make +See the [building from source][] section of the `README` for instructions. Make sure that all tests pass prior to submitting your pull request. @@ -272,7 +273,7 @@ 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. -1. Add any additional information and ask questions; start a conversation, or +1. Add any additional information and ask questions; start a conversation or continue one from JIRA 1. Mention the JIRA issue ID 1. Also mention that you have submitted the CLA as described above @@ -300,8 +301,8 @@ 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. i.e. you do not need to -issue a new pull request when asked to make changes. +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. [help documentation]: http://help.github.com/send-pull-requests [JIRA issue tracker]: https://jira.springsource.org/browse/SPR