CONTRIBUTING.asciidoc

   1 = Making a contribution
   2
   3 This is a contributor guide inspired by the https://github.com/agis-/git-style-guide[Git Style Guide] which in turn was inspired by the https://www.kernel.org/doc/Documentation/SubmittingPatches[How to Get Your Change Into the Linux Kernel] documentation and various other places.
   4
   5 If you feel like contributing, please do so! Fork the project and open a pull request.
   6
   7 == Table of contents
   8
   9 * link:#copyright[Copyright]
  10 * link:#branches[Branches]
  11 * link:#commits[Commits]
  12 ** link:#messages[Messages]
  13 * link:#merging[Merging]
  14 * link:#misc[Misc.]
  15
  16
  17 [[copyright]]
  18 == Copyright
  19
  20 * In case you are want to submit code, you have to agree to the licensing terms of this project. Do so by using `gpg` to sign the WAIVER file included in this project:
  21
  22 [source, shell]
  23 -----
  24 $ gpg2 --no-version --armor --sign AUTHORS/WAIVER
  25
  26 # or using 'make'
  27 $ make sign-waiver
  28 -----
  29
  30 * After that, add the signed file into the *AUTHORS* folder. Rename it to `WAIVER-signed-by-YOUR_NAME.asc`.
  31
  32 [source, shell]
  33 -----
  34 $ mv AUTHORS/WAIVER.asc AUTHORS/WAIVER-signed-by-YOUR_NAME.asc
  35 -----
  36
  37
  38 [[branches]]
  39 == Branches
  40
  41 * Branch names are called *issue-ISSUE_NUMBER*, e.g. *issue-123*.
  42
  43 [source, shell]
  44 -----
  45 # good
  46 $ git checkout -b issue-123
  47
  48 # bad - no reference to the actual issue
  49 $ git checkout -b login_fix
  50 -----
  51
  52 * When several people are working on the *same* feature, it might be convenient to have *personal* feature branches and a *team-wide* feature branch. In that case, suffix the name of branch with a slash, followed by the person's name for the personal branches and *master* for the team-wide branch:
  53
  54 [source, shell]
  55 -----
  56 # team-wide branch
  57 $ git checkout -b issue-123/master
  58
  59 # Adam's branch
  60 $ git checkout -b issue-123/adam
  61
  62 # Eve's branch
  63 $ git checkout -b issue-123/eve
  64 -----
  65
  66 * link:#merging[Merge] at will the personal branches to the team-wide branch *after* rebasing onto it (in order to maintain a simple history). Eventually, the team-wide branch will be merged to `master`.
  67
  68 * Delete your branch from the upstream repository after it's merged (unless there is a specific reason not to). Tip: Use the following command to list merged branches:
  69
  70 [source, shell]
  71 -----
  72 $ git branch --merged master | grep -v "\* master"
  73 -----
  74
  75
  76 [[commits]]
  77 == Commits
  78
  79 * Each commit should be a single *logical change*. Don't make several *logical changes* in one commit. For example, if a patch fixes a bug and optimizes the performance of a feature, split it into two separate commits.
  80
  81 * Don't split a single *logical change* into several commits. For example, the implementation of a feature and the corresponding tests should be in the same commit.
  82
  83 * Commit *early* and *often*. Small, self-contained commits are easier to understand and revert when something goes wrong.
  84
  85 * Commits should be ordered *logically*. For example, if *commit X* depends on changes done in *commit Y*, then *commit Y* should come before *commit X*.
  86
  87
  88 [[messages]]
  89 === Messages
  90
  91 * The summary line should look like this:
  92
  93 `#ISSUE_NUMBER - ISSUE_TITLE`
  94
  95 * After that should come a blank line following by a more thorough description. It should be wrapped to *72 characters* and explain *why* the change is needed, *how* it addresses the issue and what *side-effects* it might have.
  96
  97 * After that the following reference to the issue is expected:
  98
  99 `Task-Url: https://github.com/sebhoss/generic-types/issues/issue/ISSUE_NUMBER`
 100
 101 * Finally, the signed-off line is expected to look like this:
 102
 103 `Signed-off-by: FIRST_NAME LAST_NAME <email@address.com>`
 104
 105 * Ultimately, when writing a commit message, think about what you would need to know if you run across the commit in a year from now.
 106
 107 * If a *commit A* depends on another *commit B*, the dependency should be stated in the message of *commit A*. Use the commit's hash when referring to commits.
 108
 109 * Similarly, if *commit A* solves a bug introduced by *commit B*, it should be stated in the message of *commit A*.
 110
 111 * If a commit is going to be squashed to another commit use the `--squash` and
 112   `--fixup` flags respectively, in order to make the intention clear:
 113
 114 `$ git commit --squash f387cab2`
 115
 116 * Tip: Use the `--autosquash` flag when rebasing. The marked commits will be squashed automatically.
 117
 118
 119 [[merging]]
 120 == Merging
 121
 122 * *Do not rewrite published history.* The repository's history is valuable in its own right and it is very important to be able to tell *what actually happened*. Altering published history is a common source of problems for anyone working on the project.
 123
 124 * However, there are cases where rewriting history is legitimate. These are when:
 125
 126 - You are the only one working on the branch and it is not being reviewed.
 127 - You want to tidy up your branch (eg. squash commits) and/or rebase it onto the "master" in order to merge it later.
 128
 129 * That said, *never rewrite the history of the "master" branch* or any other special branches (ie. used by production or CI servers).
 130
 131 * Keep the history *clean* and *simple*. *Just before you merge* your branch:
 132
 133 - Make sure it conforms to the style guide and perform any needed actions if it doesn't (squash/reorder commits, reword messages etc.)
 134 - Rebase it onto the branch it's going to be merged to and do the merge after:
 135
 136 [source,shell]
 137 -----
 138 [my-branch] $ git fetch
 139 [my-branch] $ git rebase origin/master
 140 -----
 141
 142 * This results in a branch that can be applied directly to the end of the "master" branch and results in a very simple history.
 143
 144 * Note: This strategy is better suited for projects with short-running branches. Otherwise it might be better to occassionally merge the "master" branch instead of rebasing onto it.
 145
 146 * All merges are expected to be handled by GitHubs pull request feature.
 147
 148
 149 [[misc]]
 150 == Misc.
 151
 152 * *Test before you push.* Do not push half-done work.
 153
 154 * Use http://git-scm.com/book/en/v2/Git-Basics-Tagging#Annotated-Tags[annotated tags] for marking releases or other important points in the history.
 155
 156 * Prefer http://git-scm.com/book/en/v2/Git-Basics-Tagging#Lightweight-Tags[lightweight tags] for personal use, such as to bookmark commits for future reference.
 157
 158 * Keep your repositories at a good shape by performing maintenance tasks occasionally, in your local *and* remote repositories:
 159
 160 ** http://git-scm.com/docs/git-gc[`git-gc(1)`]
 161 ** http://git-scm.com/docs/git-prune[`git-prune(1)`]
 162 ** http://git-scm.com/docs/git-fsck[`git-fsck(1)`]