From a20702fc59b293849d4e44799b380f11b5780669 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 5 Oct 2012 00:28:12 +0200
Subject: Add CONTRIBUTING.md file

---
 CONTRIBUTING.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 CONTRIBUTING.md

(limited to 'CONTRIBUTING.md')

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..86fcc9f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,137 @@
+Contributing
+============
+
+Introduction
+------------
+
+This document describes the usages and rules to follow when contributing
+to this project.
+
+It uses the uppercase keywords SHOULD for optional but highly recommended
+conditions and MUST for required conditions.
+
+`git` is a distributed source code versioning system. This document refers
+to three different repositories hosting the source code of the project.
+`Your local copy` refers to the copy of the repository that you have on
+your computer. The remote repository `origin` refers to your fork of the
+project's repository that you can find in your GitHub account. The remote
+repository `upstream` refers to the official repository for this project.
+
+Following this document will ensure prompt merging of your work in the
+`master` branch of the project.
+
+Planning
+--------
+
+Upon identifying a bug, you SHOULD submit a ticket, regardless of your
+plans for fixing it. If you plan to fix the bug, you SHOULD discuss your
+plans to avoid having your work rejected.
+
+Before implementing a new feature, you SHOULD submit a ticket for discussion
+on your plans. The feature might have been rejected already, or the
+implementation might already be decided.
+
+Cloning
+-------
+
+You MUST fork the project's repository to your GitHub account by clicking
+on the `Fork` button.
+
+Then, from your fork's page, copy the `Git Read-Only` URL to your clipboard.
+You MUST perform the following commands in the folder you choose, replacing
+`$URL` by the URL you just copied, `$UPSTREAM_URL` by the `Git Read-Only`
+project of the official repository, and `$PROJECT` by the name of this project.
+
+``` bash
+$ git clone "$URL"
+$ cd $PROJECT
+$ git remote add upstream $UPSTREAM_URL
+```
+
+Branching
+---------
+
+Before starting working on the code, you MUST update to `upstream`. The
+project is always evolving, and as such you SHOULD always strive to keep
+up to date when submitting patches to make sure they can be merged without
+conflicts.
+
+To update the current branch to `upstream`, you can use the following commands.
+
+``` bash
+$ git fetch upstream
+$ git rebase upstream/master
+```
+
+It may ask you to stash your changes, in which case you stash with:
+
+``` bash
+$ git stash
+```
+
+And put your changes back in with:
+
+``` bash
+$ git stash pop
+```
+
+You SHOULD use these commands both before working on your patch and before
+submitting the pull request. If conflicts arise it is your responsability
+to deal with them.
+
+You MUST create a new branch for your work. First, ensure you are on `master`.
+You MUST update `master` to `upstream` before doing anything. Then create a
+new branch `$BRANCH` and switch to it.
+
+``` bash
+$ git checkout -b $BRANCH
+```
+
+You MUST use a an insightful branch name.
+
+If you later need to switch back to an existing branch `$BRANCH`, you can use:
+
+``` bash
+$ git checkout $BRANCH
+```
+
+Source editing
+--------------
+
+The following rules MUST be followed:
+ *  Indentation uses horizontal tabs, 1 tab equals the length of 4 space chars
+ *  Do NOT align code; only indentation is allowed
+
+The following rules SHOULD be followed:
+ *  Write small functions whenever possible
+ *  Avoid having too many clauses containing clauses containing clauses
+
+Committing
+----------
+
+You MUST ensure that all commits pass all tests and do not have extra
+Dialyzer warnings.
+
+You MUST put all the related work in a single commit. Fixing a bug is one
+commit, adding a feature is one commit, adding two features is two commits.
+
+You MUST write a proper commit title and message. The commit title MUST be
+at most 72 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, you MUST make
+all lines smaller than 80 characters. You SHOULD explain what the commit
+does, what references you used and any other information that helps
+understanding your work.
+
+Submitting the pull request
+---------------------------
+
+You MUST push your branch `$BRANCH` to GitHub, using the following command:
+
+``` bash
+$ git push origin $BRANCH
+```
+
+You MUST then submit the pull request by using the GitHub interface.
+You SHOULD provide an explanatory message and refer to any previous ticket
+related to this patch.
-- 
cgit v1.2.3