doc: Update CONTRIBUTING.md

Let's add more information which could avoid contributors to waste their time
and CI resources.

Signed-off-by: Guillaume Abrioux <gabrioux@redhat.com>

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 530cecdd1db0944a67f250b0aebedd783782e116..c80afd8db216e8a526b14a2bbdac418a411997af 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -31,3 +31,50 @@ We use Jenkins to run several tests on each pull request.
 
 If you don't want to run a build for a particular pull request, because all you are changing is the
 README for example, add the text `[skip ci]` to the PR title.
+
+Good to know
+------------
+
+#### Sample files
+The sample files we provide in `group_vars/` are versionned,
+they are a copy of what their respective `./roles/<role>/defaults/main.yml` contain.
+
+It means if you are pushing a patch modifying one of these files:
+
+- `./roles/ceph-mds/defaults/main.yml`
+- `./roles/ceph-mgr/defaults/main.yml`
+- `./roles/ceph-fetch-keys/defaults/main.yml`
+- `./roles/ceph-rbd-mirror/defaults/main.yml`
+- `./roles/ceph-agent/defaults/main.yml`
+- `./roles/ceph-defaults/defaults/main.yml`
+- `./roles/ceph-osd/defaults/main.yml`
+- `./roles/ceph-nfs/defaults/main.yml`
+- `./roles/ceph-client/defaults/main.yml`
+- `./roles/ceph-common/defaults/main.yml`
+- `./roles/ceph-iscsi-gw/defaults/main.yml`
+- `./roles/ceph-mon/defaults/main.yml`
+- `./roles/ceph-rgw/defaults/main.yml`
+- `./roles/ceph-restapi/defaults/main.yml`
+- `./roles/ceph-docker-common/defaults/main.yml`
+- `./roles/ceph-common-coreos/defaults/main.yml`
+
+You will have to get the corresponding sample file updated, there is a script which do it for you.
+You must run `./generate_group_vars_sample.sh` before you commit your changes so you are guaranteed to have consistent content for these files.
+
+
+#### Keep your branch up-to-date
+Sometimes, a pull request can be subject to long discussion, reviews and comments, meantime, `master`
+moves forward so let's try to keep your branch rebased on master regularly to avoid huge conflict merge.
+A rebased branch is more likely to be merged easily & shorter.
+
+
+#### Organize your commits
+Do not split your commits unecessary, we are used to see pull request with useless additional commits like
+"I'm addressing reviewer's comments". So, please, squash and/or amend them as much as possible.
+
+Similarly, split them when needed, if you are modifying several parts in ceph-ansible or pushing a large
+patch you may have to split yours commit properly so it's better to understand your work.
+Some recommandations:
+ - 1 fix = 1 commit,
+ - do not mix multiple topics in a single commit,
+ - if you PR contains a large number of commits that are each other totally unrelated, it should probably even be split in several PRs.