CONTRIBUTING.org

#+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