git notes

[ci skip]

1 files changed, 20 insertions, 3 deletions

diff --git a/doc/contributing.rst b/doc/contributing.rst
index 0d160c680..64b609af5 100644
--- a/doc/contributing.rst
+++ b/doc/contributing.rst
@@ -112,9 +112,11 @@ Sending patches
 ========================================
 
 All contributions should be submitted as pull requests via GitHub
-(https://github.com/randombit/botan). If you are planning a large change email
-the mailing list or open a discussion ticket on github before starting out to
-make sure you are on the right path.
+(https://github.com/randombit/botan). If you are planning a large
+change email the mailing list or open a discussion ticket on github
+before starting out to make sure you are on the right path. And once
+you have something written, free to open a [WIP] PR for early review
+and comment.
 
 If possible please sign your git commits using a PGP key.
 See https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work for
@@ -136,6 +138,21 @@ Also, try building and testing it on whatever hardware you have handy,
 especially non-x86 platforms, or especially C++11 compilers other than the
 regularly tested GCC, Clang, and Visual Studio compilers.
 
+Git Usage
+========================================
+
+Do *NOT* merge ``master`` into your topic branch, this creates
+needless commits and noise in history. Instead, as needed, rebase your
+branch against master (``git rebase -i master``) and force push the
+branch to update the PR. If the GitHub PR page does not report any
+merge conflicts and nobody asks you to rebase, you don't need to
+rebase.
+
+Try to keep your history clean and use rebase to squash your commits
+as needed. If your diff is less than roughly 100 lines, it should
+probably be a single commit. Only split commits as needed to help with
+review/understanding of the change.
+
 External Dependencies
 ========================================