1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
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
`next` branch of the project. The `master` branch has `next` merged to
it when we are satisfied with stability of the branch and any new
features. Please submit all pull requests to the `next` branch and
base your work off the `upstream` `next` branch.
Reporting bugs
--------------
Upon identifying a bug you SHOULD submit a ticket, regardless of your
plan 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/next
```
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 `next`.
You MUST update `next` 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 4 horizontal spaces
* Tabs should not be used
* 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
* Lines SHOULD NOT span more than 80 columns
When in doubt indentation as performed in the Erlang Emacs Mode is
correct.
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 to
the `next` branch. You SHOULD provide an explanatory message and refer
to any previous ticket related to this patch.
|
