From 30bce7fa169df320bbff8e56efe9610449a9d60b Mon Sep 17 00:00:00 2001 From: Chris Beams Date: Tue, 18 Sep 2012 12:53:40 +0100 Subject: [PATCH] Add CONTRIBUTING.md Copied from the Contributor Guidelines wiki document [1] in order to take advantage of GitHub's new integrated support for displaying a link to contributor guidelines when issuing a pull request [2]. The wiki document has been updated to link to this document. [1]: https://github.com/SpringSource/spring-framework/wiki/Contributor-guidelines [2]: https://github.com/blog/1184-contributing-guidelines --- CONTRIBUTING.md | 307 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 307 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..f06867ea7d7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,307 @@ +_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._ + +_Please refer back to this document as a checklist before issuing any pull +request; this will save time for everyone!_ + +## Understand the basics + +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. + +## 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 +list for prior discussions. + +## Sign the Contributor License Agreement + +If you have not previously done so, please fill out and submit the +[SpringSource CLA form][]. You'll receive a token when this process is complete. +Keep track of this, you may be asked for it later! + +Note that emailing/postal mailing a signed copy is _not_ necessary. Submission +of the web form is all that is required. + +When you've completed the web form, simply add the following in a comment on +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 +future pull requests as well, simply so the Spring Framework team knows +immediately that this process is complete. + + +## Create your branch from `master` + +At any given time, Spring Framework's `master` branch represents the version +currently under development. For example, if 3.1.1 was the latest Spring +Framework release, `master` represents 3.2.0 development, and the `3.1.x` +branch represents 3.1.2 development. + +Create your topic branch to be submitted as a pull request from `master`. The +Spring team will consider your pull request for backporting to maintenance +versions (e.g. 3.1.2) on a case-by-case basis; you don't need to worry about +submitting anything for backporting. + + +## Use short branch names + +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 +[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. + + +## Mind the whitespace + +Please carefully follow the whitespace and formatting conventions already +present in the framework. + +1. Tabs, not spaces +1. Unix (LF), not dos (CRLF) line endings +1. Eliminate all trailing whitespace +1. Wrap Javadoc at 90 characters +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. +1. Latin-1 (ISO-8859-1) encoding for Java sources; use `native2ascii` to convert + if necessary + + +## Add Apache license header to all new classes + +```java +/* + * Copyright 2002-2012 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package ...; +``` + +## Update Apache license header to modified files as necessary + +Always check the date range in the license header. For example, if you've +modified a file in 2012 whose header still reads + +```java + * Copyright 2002-2011 the original author or authors. +``` + +then be sure to update it to 2012 appropriately + +```java + * Copyright 2002-2012 the original author or authors. +``` + +## Use @since tags for newly-added public API types and methods + +e.g. + +```java +/** + * ... + * + * @author First Last + * @since 3.2 + * @see ... + */ +``` + +## 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. + +```java +package org.springframework.beans.factory.support; + +/** + * 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 { + + @Test + public void cornerSpr8954() { + // ... + } +} +``` + + +## 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 real name in git commits + +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: + + Author: Nickname + +Rather, please include your first and last name, properly capitalized, as +submitted against the SpringSource contributor license agreement: + + Author: First Last + +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 + + 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: + + cd spring-framework + git config user.name "First Last" + git config user.email user@mail.com + + +## Format commit messages + +Please read and follow the [commit guidelines section of Pro Git][]. + +Most importantly, please format your commit messages in the following way +(adapted from the commit template in the link above): + + 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" +1. Begin the subject line sentence 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. 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 +1. 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/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 all tests prior to submission + +See the [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 + +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. +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 + +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 + +Add a comment to the associated JIRA issue(s) linking to your new pull request. + + +## 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. i.e. 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 +[spring-framework-contrib]: https://groups.google.com/forum/#!forum/spring-framework-contrib +[SpringSource CLA form]: https://support.springsource.com/spring_committer_signup +[fork-and-edit]: https://github.com/blog/844-forking-with-the-edit-button +[commit guidelines section of Pro Git]: http://progit.org/book/ch5-2.html#commit_guidelines +[building from source]: https://github.com/SpringSource/spring-framework#building-from-source