GH-892: Update contribution guidelines

Resolves #892

CONTRIBUTING.adoc

@@ -16,19 +16,19 @@ spring-code-of-conduct@pivotal.io.
 Not sure what a *pull request* is, or how to submit one?  Take a look at GitHub's excellent documentation:
 https://help.github.com/articles/using-pull-requests/[Using Pull Requests] first.
 
-== Search JIRA first; create an issue if necessary
+== Search GitHub (or JIRA) issues first; create one if necessary
 
-Is there already an issue that addresses your concern?  Search the
-https://jira.spring.io/browse/AMQP[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,
+Is there already an issue that addresses your concern?
+Search the https://github.com/spring-projects/spring-integration/issues[GitHub issue tracker] (and https://jira.spring.io/browse/AMQP[JIRA issue tracker]) to see if you can find something similar.
+If not, please create a new issue in GitHub before submitting a pull request unless the change is truly trivial, e.g. typo fixes,
 removing compiler warnings, etc.
 
 == Sign the contributor license agreement
 
-If you have not previously done so, please fill out and
-submit the https://cla.pivotal.io/sign/spring[Contributor License Agreement (CLA)].
+If you have not previously done so, please fill out and submit the https://cla.pivotal.io/sign/spring[Contributor License Agreement (CLA)].
 
-Very important, before we can accept any *Spring AMQP contributions*, we will need you to sign the CLA. Signing the CLA does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do.
+Very important, before we can accept any *Spring AMQP contributions*, we will need you to sign the CLA.
+Signing the CLA does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do.
 
 == Fork the Repository
 
@@ -44,45 +44,35 @@ Very important, before we can accept any *Spring AMQP contributions*, we will ne
 _you should see only 'origin' - which is the fork you created for your own github account_
 4. `git remote add upstream git@github.com:spring-projects/spring-amqp.git`
 5. `git remote show`
-_you should now see 'upstream' in addition to 'origin' where 'upstream' is the SpringSource repository from which releases are built_
+_you should now see 'upstream' in addition to 'origin' where 'upstream' is the Spring repository from which releases are built_
 6. `git fetch --all`
 7. `git branch -a`
 _you should see branches on origin as well as upstream, including 'master' and 'maint'_
 
 == A Day in the Life of a Contributor
 
-* _Always_ work on topic branches (Typically use the Jira ticket ID as the branch name).
-  - For example, to create and switch to a new branch for issue AMQP-123: `git checkout -b AMQP-123`
+* _Always_ work on topic branches (Typically use the HitHub (or JIRA) issue ID as the branch name).
+  - For example, to create and switch to a new branch for issue #123: `git checkout -b GH-123`
 * You might be working on several different topic branches at any given time, but when at a stopping point for one of those branches, commit (a local operation).
-* Please follow the "Commit Guidelines" described in
-http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project[this chapter of Pro Git].
-* Then to begin working on another issue (say AMQP-101): `git checkout AMQP-101`. The _-b_ flag is not needed if that
-branch already exists in your local repository.
+* Please follow the "Commit Guidelines" described in http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project[this chapter of Pro Git].
+* Then to begin working on another issue (say AMQP-101): `git checkout AMQP-101`. The _-b_ flag is not needed if that branch already exists in your local repository.
 * When ready to resolve an issue or to collaborate with others, you can push your branch to origin (your fork),
-e.g.: `git push origin AMQP-123`
-* If you want to collaborate with another contributor, have them fork your repository (add it as a remote) and
-`git fetch <your-username>` to grab your branch.
+e.g.: `git push origin GH-123`
+* If you want to collaborate with another contributor, have them fork your repository (add it as a remote) and `git fetch <your-username>` to grab your branch.
 Alternatively, they can use `git fetch --all` to sync their local state with all of their remotes.
-* If you grant that collaborator push access to your repository, they can even apply their changes to your branch.
-* When ready for your contribution to be reviewed for potential inclusion in the master branch of the canonical
-spring-amqp repository (what you know as 'upstream'), issue a pull request to the SpringSource repository
-(for more detail, see https://help.github.com/articles/using-pull-requests/[Using pull requests]).
-* The project lead may merge your changes into the upstream master branch as-is, he may keep the pull request open yet
-add a comment about something that should be modified, or he might reject the pull request by closing it.
+* If you grant those collaborator(s) push access to your repository, they can even apply their changes to your branch.
+* When ready for your contribution to be reviewed for potential inclusion in the master branch of the canonical spring-amqp repository (what you know as 'upstream'), issue a pull request to the SpringSource repository (for more detail, see https://help.github.com/articles/using-pull-requests/[Using pull requests]).
+* The project lead may merge your changes into the upstream master branch as-is, he may keep the pull request open yet add a comment about something that should be modified, or he might reject the pull request by closing it.
 * A prerequisite for any pull request is that it will be cleanly merge-able with the upstream master's current state.
 **This is the responsibility of any contributor.**
-If your pull request cannot be applied cleanly, the project lead will most likely add a comment requesting that you make
-it merge-able.
+If your pull request cannot be applied cleanly, the project lead will most likely add a comment requesting that you make it merge-able.
 For a full explanation, see http://git-scm.com/book/en/Git-Branching-Rebasing[the Pro Git section on rebasing].
-As stated there: _"> Often, you’ll do this to make sure your commits apply cleanly on a remote branch — perhaps in a
-project to which you’re trying to contribute but that you don’t maintain."_
+As stated there: _"> Often, you’ll do this to make sure your commits apply cleanly on a remote branch — perhaps in a project to which you’re trying to contribute but that you don’t maintain."_
 
 == Keeping your Local Code in Sync
-* As mentioned above, you should always work on topic branches (since 'master' is a moving target). However, you do want
-to always keep your own 'origin' master branch in synch with the 'upstream' master.
+* As mentioned above, you should always work on topic branches (since 'master' is a moving target). However, you do want to always keep your own 'origin' master branch in synch with the 'upstream' master.
 * Within your local working directory, you can sync up all remotes' branches with: `git fetch --all`
-* While on your own local master branch: `git pull upstream master` (which is the equivalent of fetching upstream/master
-and merging that into the branch you are in currently)
+* While on your own local master branch: `git pull upstream master` (which is the equivalent of fetching upstream/master and merging that into the branch you are in currently)
 * Now that you're in synch, switch to the topic branch where you plan to work, e.g.: `git checkout -b AMQP-123`
 * When you get to a stopping point: `git commit`
 * If changes have occurred on the upstream/master while you were working you can synch again:
@@ -91,19 +81,13 @@ and merging that into the branch you are in currently)
     - Switch back to the topic branch: `git checkout AMQP-123` (no -b needed since the branch already exists)
     - Rebase the topic branch to minimize the distance between it and your recently synched master branch: `git rebase master`
 (Again, for more detail see http://git-scm.com/book/en/Git-Branching-Rebasing[the Pro Git section on rebasing]).
-* **Note** You cannot rebase if you have already pushed your branch to your remote because you'd be rewriting history
-(see **'The Perils of Rebasing'** in the article).
-If you rebase by mistake, you can undo it as discussed
-http://stackoverflow.com/questions/134882/undoing-a-git-rebase[in this stackoverflow discussion].
-Once you have published your branch, you need to merge in the master rather than rebasing.
-* Now, if you issue a pull request, it is much more likely to be merged without conflicts.
-Most likely, any pull request that would produce conflicts will be deferred until the issuer of that pull request makes
-these adjustments.
+* **Note** While it is generally recommended to __not__ re-write history by using `push --force`, and we do not do this on `master` (and release) branches in the main repo, we require topic branches for pull requests to be rebased before merging, in order to maintain a clean timeline and avoid "merge" commits.
+* If, while rebasing for the merge, we find significant conflicts, we may ask you to rebase and `push --force` to your topic branch after resolving the conflicts.
 * Assuming your pull request is merged into the 'upstream' master, you will actually end up pulling that change into
 your own master eventually, and at that time, you may decide to delete the topic branch from your local repository and
 your fork (origin) if you pushed it there.
-    - to delete the local branch: `git branch -d AMQP-123`
-    - to delete the branch from your origin: `git push origin :AMQP-123`
+    - to delete the local branch: `git branch -d GH-123`
+    - to delete the branch from your origin: `git push origin :GH-123`
 
 == Maintain a linear commit history
 
@@ -207,20 +191,24 @@ Use @since tags for newly-added public API types and methods e.g.
 
 == 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.
+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 GitHub issue basis.
 
 == 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.
+**Do not** squash commits after a PR is issued against the branch - especially after resolving issues from the review; just add more commits to the branch; it is easier to see what changed since the review.
+The committer will generally squash the commits before the final merge.
 
 == Use your 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:
+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 <user@mail.com>
 
-Rather, please include your first and last name, properly capitalized, as submitted against the SpringSource contributor license agreement:
+Rather, please include your first and last name, properly capitalized, as submitted against the SpringIO contributor license agreement:
 
     Author: First Last <user@mail.com>
 
@@ -245,18 +233,17 @@ Make sure that all tests pass prior to submitting your pull 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.
+If the change is to resolve a legazy JIRA issue, add a comment to the associated JIRA issue(s) linking to your new pull request.
 
-== Provide a Link to the JIRA issue in the Associated Pull Request
+== Provide a Link to the GitHub issue in the associated Pull Request
 
-Add a JIRA issue link to your first commit comment of the pull request, so your commit message
+Add a GitHib issue link to your first commit comment of the pull request, so your commit message
 may look like this:
 
 ----
-AMQP-563: Support Explicit Temporary Reply Queue
+GH-123: Title up to 50 characters total
 
-JIRA: https://jira.spring.io/browse/AMQP-563
+Fixes https://github.com/spring-projects/spring-amqp/issues/123
 
-Allow user to override the use of direct reply-to when the broker supports it and use a
-temporary reply queue for request/reply.
+Text about the problem and how it was fixed.
 ----