1Contributing code to Kyua 2========================= 3 4Want to contribute? Great! But first, please take a few minutes to read this 5document in full. Doing so upfront will minimize the turnaround time required 6to get your changes incorporated. 7 8 9Legal notes 10----------- 11 12* Before we can use your code, you must sign the 13 [Google Individual Contributor License 14 Agreement](https://developers.google.com/open-source/cla/individual), 15 also known as the CLA, which you can easily do online. The CLA is necessary 16 mainly because you own the copyright to your changes, even after your 17 contribution becomes part of our codebase, so we need your permission to use 18 and distribute your code. We also need to be sure of various other 19 things--for instance that you will tell us if you know that your code 20 infringes on other people's patents. You do not have to sign the CLA until 21 after you have submitted your code for review and a member has approved it, 22 but you must do it before we can put your code into our codebase. 23 24* Contributions made by corporations are covered by a different agreement than 25 the one above: the 26 [Google Software Grant and Corporate Contributor License 27 Agreement](https://developers.google.com/open-source/cla/corporate). 28 Please get your company to sign this agreement instead if your contribution is 29 on their behalf. 30 31* Unless you have a strong reason not to, please assign copyright of your 32 changes to Google Inc. and use the 3-clause BSD license text included 33 throughout the codebase (see [LICENSE](LICENSE)). Keeping the whole project 34 owned by a single entity is important, particularly to avoid the problem of 35 having to replicate potentially hundreds of different copyright notes in 36 documentation materials, etc. 37 38 39Communication 40------------- 41 42* Before you start working on a larger contribution, you should get in touch 43 with us first through the 44 [kyua-discuss mailing 45 list](https://groups.google.com/forum/#!forum/kyua-discuss) 46 with your idea so that we can help out and possibly guide you. Coordinating 47 upfront makes it much easier to avoid frustration later on. 48 49* Subscribe to the 50 [kyua-log mailing list](https://groups.google.com/forum/#!forum/kyua-log) to 51 get notifications on new commits, Travis CI results, or changes to bugs. 52 53 54Git workflow 55------------ 56 57* Always work on a non-master branch. 58 59* Make sure the history of your branch is clean. (Ab)use `git rebase -i master` 60 to ensure the sequence of commits you want pulled is easy to follow and that 61 every commit does one (and only one) thing. In particular, commits of the 62 form `Fix previous` or `Fix build` should never ever exist; merge those fixes 63 into the relevant commits so that the history is clean at pull time. 64 65* Always trigger Travis CI builds for your changes (hence why working on a 66 branch is important). Push your branch to GitHub so that Travis CI picks it 67 up and performs a build. If you have forked the repository, you may need to 68 enable Travis CI builds on your end. Wait for a green result. 69 70* It is OK and expected for you to `git push --force` on **non-master** 71 branches. This is required if you need to go through the commit/test cycle 72 more than once for any given branch after you have "fixed-up" commits to 73 correct problems spotted in earlier builds. 74 75* Do not send pull requests that subsume other/older pull requests. Each major 76 change being submitted belongs in a different pull request, which is trivial 77 to achieve if you use one branch per change as requested in this workflow. 78 79 80Code reviews 81------------ 82 83* All changes will be subject to code reviews pre-merge time. In other words: 84 all pull requests will be carefully inspected before being accepted and they 85 will be returned to you with comments if there are issues to be fixed. 86 87* Be careful of stylistic errors in your code (see below for style guidelines). 88 Style violations hinder the review process and distract from the actual code. 89 By keeping your code clean of style issues upfront, you will speed up the 90 review process and avoid frustration along the way. 91 92* Whenever you are ready to submit a pull request, review the *combined diff* 93 you are requesting to be pulled and look for issues. This is the diff that 94 will be subject to review, not necessarily the individual commits. You can 95 view this diff in GitHub at the bottom of the `Open a pull request` form that 96 appears when you click the button to file a pull request, or you can see the 97 diff by typing `git diff <your-branch> master`. 98 99 100Commit messages 101--------------- 102 103* Follow standard Git commit message guidelines. The first line has a maximum 104 length of 50 characters, does not terminate in a period, and has to summarize 105 the whole commit. Then a blank line comes, and then multiple plain-text 106 paragraphs provide details on the commit if necessary with a maximum length of 107 72-75 characters per line. Vim has syntax highlighting for Git commit 108 messages and will let you know when you go above the maximum line lengths. 109 110* Use the imperative tense. Say `Add foo-bar` or `Fix baz` instead of `Adding 111 blah`, `Adds bleh`, or `Added bloh`. 112 113 114Handling bug tracker issues 115--------------------------- 116 117* All changes pushed to `master` should cross-reference one or more issues in 118 the bug tracker. This is particularly important for bug fixes, but also 119 applies to major feature improvements. 120 121* Unless you have a good reason to do otherwise, name your branch `issue-N` 122 where `N` is the number of the issue being fixed. 123 124* If the fix to the issue can be done *in a single commit*, terminate the commit 125 message with `Fixes #N.` where `N` is the number of the issue being fixed and 126 include a note in `NEWS` about the issue in the same commit. Such fixes can 127 be merged onto master using fast-forward (the default behavior of `git 128 merge`). 129 130* If the fix to the issue requires *more than one commit*, do **not** include 131 `Fixes #N.` in any of the individual commit messages of the branch nor include 132 any changes to the `NEWS` file in those commits. These "announcement" changes 133 belong in the merge commit onto `master`, which is done by `git merge --no-ff 134 --no-commit your-branch`, followed by an edit of `NEWS`, and terminated with a 135 `git commit -a` with the proper note on the bug being fixed. 136 137 138Style guide 139----------- 140 141These notes are generic and certainly *non-exhaustive*: 142 143* Respect formatting of existing files. Note where braces are placed, number of 144 blank lines between code chunks, how continuation lines are indented, how 145 docstrings are typed, etc. 146 147* Indentation is *always* done using spaces, not tabs. The only exception is in 148 `Makefile`s, where any continuation line within a target must be prefixed by a 149 *single tab*. 150 151* [Be mindful of spelling and 152 grammar.](http://julipedia.meroh.net/2013/06/readability-mind-your-typos-and-grammar.html) 153 Mistakes of this kind are enough of a reason to return a pull request. 154 155* Use proper punctuation for all sentences. Always start with a capital letter 156 and terminate with a period. 157 158* Respect lexicographical sorting wherever possible. 159 160* Lines must not be over 80 characters. 161 162* No trailing whitespace. 163 164* Two spaces after end-of-sentence periods. 165 166* Two blank lines between functions. If there are two blank lines among code 167 blocks, they usually exist for a reason: keep them. 168 169* In C++ code, prefix all C identifiers (those coming from `extern "C"` 170 includes) with `::`. 171 172* Getter functions/methods only need to be documented via `\return`. A 173 redundant summary is not necessary. 174