Add amending-commits.md

contribution-guidelines.md

@@ -56,6 +56,9 @@ properly written. It checks the following:
   [setup_commit_msg_hook.sh](dev/tools/hooks/setup_commit_msg_hook.sh)
   script which will setup a Git commit-msg hook that will add the above
   trailers to all the commit messages you write.
+
+See the [documentation about amending commits](docs/amending-commits.md)
+for explanation about how you can rework commit messages.
 
 Some example commit messages:
 

docs/amending-commits.md

@@ -0,0 +1,141 @@
+## How to amend commits
+
+Amending commits is useful to improve the quality of existing commits
+for example after code review or after an automatic tool, like GitCop,
+found problems in some commits.
+
+Note that this should not be done on commits that are in an official
+branch. It should be done on local only commits or on commits that are
+in a not yet merged pull request.
+
+### Improving commit messages
+
+* Note on the `commit-msg` hook
+
+After editing or creating a commit message, Git runs the commit-msg
+hook, if it has been set up. And this hook can modify the just edited
+or created commit message.
+
+This works even when editing the commit message did not change it. So
+the commit message could still end up being changed by the commit-msg
+hook.
+
+More information about Git Hooks is available on:
+
+http://git-scm.com/book/uz/v2/Customizing-Git-Git-Hooks
+
+* Improving the commit message of the last commit
+
+It's vey easy to improve the commit message of the last commit on the
+current branch. Just run:
+
+```
+$ git commit --amend
+```
+
+It will open an editor for you to change the commit message, and, when
+you save and close the editor, it will replace the last commit with a
+new one that has the improved commit message.
+
+This means that if you used the
+[setup_commit_msg_hook.sh script](dev/tools/hooks/setup_commit_msg_hook.sh)
+to automatically add some trailers if they are not there, then running
+`git commit --amend` and then saving and closing the editor is enough
+for the missing trailers if any to be added.
+
+* Improving the commit message of any commit
+
+It's also easy to improve the commit message of let's say the last 3
+commits on the current branch. Just run:
+
+```
+$ git rebase -i HEAD~3
+```
+
+It will open an instruction sheet (which is sometimes called a TODO
+list) in your editor where you can specify how commits should be
+rebased. There you just need to replace the "pick" instruction at the
+beginning of some lines with "r" (or "reword").
+
+For example change:
+
+```
+pick 06f6e99 merkledag spec
+pick 02b20bf records spec
+pick 4d30c14 dht spec
+```
+
+to:
+
+```
+r 06f6e99 merkledag spec
+r 02b20bf records spec
+r 4d30c14 dht spec
+```
+
+When you save and close the instruction sheet, for each line with the
+"r" instruction, Git will open an editor for you to change the commit
+message of the commit that follow the "r" instruction.
+
+This means that, as when using `git commit --amend`, if you used the
+[setup_commit_msg_hook.sh script](dev/tools/hooks/setup_commit_msg_hook.sh)
+then saving and closing the editor for each commit message is enough
+for the missing trailers, if any, to be added.
+
+### Updating/Rebasing some commits
+
+Sometimes a developer starts working on some features on a "dev"
+branch. And then, when the work is ready to be merged, people realize
+that some other features have been added to the "master" branch since
+the developer started working.
+
+In this case some projects are ok with merging the "dev" branch as is
+into the "master" branch, but on IPFS related projects we often prefer
+to have people rebase their work before merging it. The main reason
+for that is that it simplifies the history graph. So we often ask
+people to rebase their work.
+
+To do that you first need to fetch from the GitHub repository using:
+
+```
+$ git fetch
+```
+
+This will make sure you are uptodate regarding upstream. And then
+you can rebase using:
+
+```
+git rebase orgin/master
+```
+
+Make sure you are on the branch you want to rebase (using for example
+`git checkout dev`) though before rebasing.
+
+### Editing the last commit
+
+To edit the last commit, you can make changes, stage them (using
+git-add for example) and then run `git commit --amend`.
+
+Another way is to just make changes and then run
+`git commit --amend <path>...`
+where <path>... are the paths with the changes you want to see changed
+in the last commit.
+
+Anyway have a look at git-commit and its --amend option:
+
+http://git-scm.com/docs/git-commit
+
+### Squashing, removing and reordening commits, or editing old commits
+
+Have a look at git-rebase and its interactive mode (option -i or
+--interactive), it is very powerful, and used very often by a lot of
+great developers:
+
+http://git-scm.com/docs/git-rebase
+
+### More documentation
+
+The following links have interesting documentation on this subject:
+
+https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#cleaning-up-history
+http://git-scm.com/book/en/v2/Git-Tools-Rewriting-History