| #+OPTIONS: ^:nil |
| #+TITLE: Contributing to Triq |
| |
| ** Check for existing discussion of the change |
| :PROPERTIES: |
| :CUSTOM_ID: contributing-to-triq |
| :END: |
| |
| Before implementing a new feature, please submit a ticket to discuss |
| your plans. The feature might have been rejected already, or the |
| implementation might already be decided. |
| |
| ** Code style |
| :PROPERTIES: |
| :CUSTOM_ID: code-style |
| :END: |
| |
| The following rules must be followed: |
| |
| - Do not introduce trailing whitespace |
| - Do not mix spaces and tabs |
| - Do not introduce lines longer than 80 characters |
| |
| The following rules should be followed: |
| |
| - Write small functions whenever possible |
| - Avoid having too many clauses containing clauses containing clauses. |
| Basically, avoid deeply nested functions. |
| |
| [[http://www.erlang.org/doc/man/erlang.el.html][erlang-mode (emacs)]] indentation is preferred. This will keep the code |
| base consistent. vi users are encouraged to give [[http://emacswiki.org/emacs/Evil][Vim emulation]] |
| ([[https://gitorious.org/evil/pages/Home][more info]]) a try. |
| |
| ** Pull requests and branching |
| :PROPERTIES: |
| :CUSTOM_ID: pull-requests-and-branching |
| :END: |
| |
| Use one topic branch per pull request. If you do that, you can add |
| extra commits or fix up buggy commits via =git rebase -i=, and update |
| the branch. The updated branch will be visible in the same pull |
| request. Therefore, you should not open a new pull request when you |
| have to fix your changes. |
| |
| Do not commit to master in your fork. |
| |
| Provide a clean branch without merge commits. |
| |
| ** Tests |
| :PROPERTIES: |
| :CUSTOM_ID: tests |
| :END: |
| |
| As a general rule, any behavioral change to Triq requires a test to go |
| with it. If there's already a test case, you may have to modify that |
| one. |
| |
| To run tests, you would do: |
| |
| #+BEGIN_EXAMPLE |
| $ make test |
| #+END_EXAMPLE |
| |
| ** Credit |
| :PROPERTIES: |
| :CUSTOM_ID: credit |
| :END: |
| |
| To give everyone proper credit in addition to the git history, please |
| feel free to append your name to =THANKS= in your first contribution. |
| |
| ** Committing your changes |
| :PROPERTIES: |
| :CUSTOM_ID: committing-your-changes |
| :END: |
| |
| *** Structuring your commits |
| :PROPERTIES: |
| :CUSTOM_ID: structuring-your-commits |
| :END: |
| |
| Fixing a bug is one commit. |
| |
| Adding a feature is one commit. |
| |
| Adding two features is two commits. |
| |
| Two unrelated changes is two commits. |
| |
| If you fix a (buggy) commit, squash (=git rebase -i=) the changes as a |
| fixup commit into the original commit. |
| |
| *** Writing Commit Messages |
| :PROPERTIES: |
| :CUSTOM_ID: writing-commit-messages |
| :END: |
| |
| It's important to write a proper commit title and description. The |
| commit title must be at most 50 characters; it is the first line of |
| the commit text. The second line of the commit text must be left |
| blank. The third line and beyond is the commit message. You should |
| write a commit message. If you do, wrap all lines at 72 characters. |
| You should explain what the commit does, what references you used, and |
| any other information that helps understanding your changes. |
| |
| Basically, structure your commit message like this: |
| |
| #+BEGIN_EXAMPLE |
| One line summary (at most 50 characters) |
| |
| Longer description (wrap at 72 characters) |
| #+END_EXAMPLE |
| |
| ***** Commit title/summary |
| :PROPERTIES: |
| :CUSTOM_ID: commit-titlesummary |
| :END: |
| |
| - At most 50 characters |
| - What was changed |
| - Imperative present tense (Fix, Add, Change) |
| |
| - =Fix bug 123= |
| - =Add 'foobar' command= |
| - =Change default timeout to 123= |
| |
| - No period |
| |
| ***** Commit description |
| :PROPERTIES: |
| :CUSTOM_ID: commit-description |
| :END: |
| |
| - Wrap at 72 characters |
| - Why, explain intention and implementation approach |
| - Present tense |