CONTRIBUTING.md

   1 # Contributing to ceph-ansible
   2
   3 1. Follow the [commit guidelines](#commit-guidelines)
   4
   5 ## Commit guidelines
   6
   7 - All commits should have a subject and a body
   8 - The commit subject should briefly describe what the commit changes
   9 - The commit body should describe the problem addressed and the chosen solution
  10   - What was the problem and solution? Why that solution? Were there alternative ideas?
  11 - Wrap commit subjects and bodies to 80 characters
  12 - Sign-off your commits
  13 - Add a best-effort scope designation to commit subjects. This could be a directory name, file name,
  14   or the name of a logical grouping of code. Examples:
  15   - library: add a placeholder module for the validate action plugin
  16   - site.yml: combine validate play with fact gathering play
  17   - rhcs: bump version to 3.0 for stable 3.1
  18 - Commits linked with an issue should trace them with :
  19   - Fixes: #2653
  20
  21 [Suggested reading.](https://chris.beams.io/posts/git-commit/)
  22
  23 ## Pull requests
  24
  25 ### Jenkins CI
  26
  27 We use Jenkins to run several tests on each pull request.
  28
  29 If you don't want to run a build for a particular pull request, because all you are changing is the
  30 README for example, add the text `[skip ci]` to the PR title.
  31
  32 ### Merging strategy
  33
  34 Merging PR is controlled by [mergify](https://mergify.io/) by the following rules:
  35
  36 - at least one approuval from a maintainer
  37 - a SUCCESS from the CI pipeline "ceph-ansible PR Pipeline"
  38
  39 If you work is not ready for review/merge, please request the DNM label via a comment or the title of your PR.
  40 This will prevent the engine merging your pull request.
  41
  42 ### Backports (maintainers only)
  43
  44 If you wish to see your work from 'master' being backported to a stable branch you can ping a maintainer
  45 so he will set the backport label on your PR. Once the PR from master is merged, a backport PR will be created by mergify,
  46 if there is a cherry-pick conflict you must resolv it by pulling the branch.
  47
  48 **NEVER** push directly into a stable branch, **unless** the code from master has diverged so much that the files don't exist in the stable branch.
  49 If that happens, inform the maintainers of the reasons why you pushed directly into a stable branch, if the reason is invalid, maintainers will immediatly close your pull request.
  50
  51 ## Good to know
  52
  53 ### Sample files
  54
  55 The sample files we provide in `group_vars/` are versionned,
  56 they are a copy of what their respective `./roles/<role>/defaults/main.yml` contain.
  57
  58 It means if you are pushing a patch modifying one of these files:
  59
  60 - `./roles/ceph-mds/defaults/main.yml`
  61 - `./roles/ceph-mgr/defaults/main.yml`
  62 - `./roles/ceph-fetch-keys/defaults/main.yml`
  63 - `./roles/ceph-rbd-mirror/defaults/main.yml`
  64 - `./roles/ceph-defaults/defaults/main.yml`
  65 - `./roles/ceph-osd/defaults/main.yml`
  66 - `./roles/ceph-nfs/defaults/main.yml`
  67 - `./roles/ceph-client/defaults/main.yml`
  68 - `./roles/ceph-common/defaults/main.yml`
  69 - `./roles/ceph-iscsi-gw/defaults/main.yml`
  70 - `./roles/ceph-mon/defaults/main.yml`
  71 - `./roles/ceph-rgw/defaults/main.yml`
  72 - `./roles/ceph-container-common/defaults/main.yml`
  73 - `./roles/ceph-common-coreos/defaults/main.yml`
  74
  75 You will have to get the corresponding sample file updated, there is a script which do it for you.
  76 You must run `./generate_group_vars_sample.sh` before you commit your changes so you are guaranteed to have consistent content for these files.
  77
  78 ### Keep your branch up-to-date
  79
  80 Sometimes, a pull request can be subject to long discussion, reviews and comments, meantime, `master`
  81 moves forward so let's try to keep your branch rebased on master regularly to avoid huge conflict merge.
  82 A rebased branch is more likely to be merged easily & shorter.
  83
  84 ### Organize your commits
  85
  86 Do not split your commits unecessary, we are used to see pull request with useless additional commits like
  87 "I'm addressing reviewer's comments". So, please, squash and/or amend them as much as possible.
  88
  89 Similarly, split them when needed, if you are modifying several parts in ceph-ansible or pushing a large
  90 patch you may have to split yours commit properly so it's better to understand your work.
  91 Some recommandations:
  92
  93 - one fix = one commit,
  94 - do not mix multiple topics in a single commit,
  95 - if you PR contains a large number of commits that are each other totally unrelated, it should probably even be split in several PRs.
  96
  97 If you've broken your work up into a set of sequential changes and each commit pass the tests on their own then that's fine.
  98 If you've got commits fixing typos or other problems introduced by previous commits in the same PR, then those should be squashed before merging.
  99
 100 If you are new to Git, these links might help:
 101
 102 - [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
 103 - [http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html)