aboutsummaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING.asciidoc
blob: 7a3bc848eff41be2425134bc2c12b9106358d7f7 (plain) (blame)
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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
= Contributing

This document is a guide on how to best contribute to this project.

== Definitions

*SHOULD* describes optional steps. *MUST* describes mandatory steps.

*SHOULD NOT* and *MUST NOT* describes pitfalls to avoid.

_Your local copy_ refers to the copy of the repository that you have
on your computer. _origin_ refers to your fork of the project. _upstream_
refers to the official repository for this project.

== Discussions

For general discussion about this project, please open a ticket.
Feedback is always welcome and may transform in tasks to improve
the project, so having the discussion start there is a plus.

Alternatively you may try the #ninenines IRC channel on Freenode,
or, if you need the discussion to stay private, you can send an
email at [email protected]

== Support

Free support is generally not available. The rule is that free
support is only given if doing so benefits most users. In practice
this means that free support will only be given if the issues are
due to a fault in the project itself or its documentation.

Paid support is available for all price ranges. Please send an
email to [email protected] for more information.

== Bug reports

You *SHOULD* open a ticket for every bug you encounter, regardless
of the version you use. A ticket not only helps the project ensure
that bugs are squashed, it also helps other users who later run
into this issue. You *SHOULD* give as much information as possible
including what commit/branch, what OS/version and so on.

You *SHOULD NOT* open a ticket if another already exists for the
same issue. You *SHOULD* instead either add more information by
commenting on it, or simply comment to inform the maintainer that
you are also affected. The maintainer *SHOULD* reply to every
new ticket when they are opened. If the maintainer didn't say
anything after a few days, you *SHOULD* write a new comment asking
for more information.

You *SHOULD* provide a reproducible test case, either in the
ticket or by sending a pull request and updating the test suite.

When you have a fix ready, you *SHOULD* open a pull request,
even if the code does not fit the requirements discussed below.
Providing a fix, even a dirty one, can help other users and/or
at least get the maintainer on the right tracks.

You *SHOULD* try to relax and be patient. Some tickets are merged
or fixed quickly, others aren't. There's no real rules around that.
You can become a paying customer if you need something fast.

== Security reports

You *SHOULD* open a ticket when you identify a DoS vulnerability
in this project. You *SHOULD* include the resources needed to
DoS the project; every project can be brought down if you have
the necessary resources.

You *SHOULD* send an email to [email protected] when you
identify a security vulnerability. If the vulnerability originates
from code inside Erlang/OTP itself, you *SHOULD* also consult
with OTP Team directly to get the problem fixed upstream.

== Feature requests

Feature requests are always welcome. To be accepted, however, they
must be well defined, make sense in the context of the project and
benefit most users.

Feature requests not benefiting most users  may only be accepted
when accompanied with a proper pull request.

You *MUST* open a ticket to explain what the new feature is, even
if you are going to submit a pull request for it.

All these conditions are meant to ensure that the project stays
lightweight and maintainable.

== Documentation submissions

You *SHOULD* follow the code submission guidelines to submit
documentation.

The documentation is available in the 'doc/src/' directory. There
are three kinds of documentation: manual, guide and tutorials. The
format for the documentation is Asciidoc.

You *SHOULD* follow the same style as the surrounding documentation
when editing existing files.

You *MUST* include the source when providing media.

== Examples submissions

You *SHOULD* follow the code submission guidelines to submit examples.

The examples are available in the 'examples/' directory.

You *SHOULD* focus on exactly one thing per example.

== Code submissions

You *SHOULD* open a pull request to submit code.

You *SHOULD* open a ticket to discuss backward incompatible changes
before you submit code. This step ensures that you do not work on
a large change that will then be rejected.

You *SHOULD* send your code submission using a pull request on GitHub.
If you can't, please send an email to [email protected] with your
patch.

The following sections explain the normal GitHub workflow.

=== Cloning

You *MUST* fork the project's repository on GitHub by clicking on the
_Fork_ button.

On the right page of your fork's page is a field named _SSH clone URL_.
Its contents will be identified as `$ORIGIN_URL` in the following snippet.

On the right side of the project's repository page is a similar field.
Its contents will be identified as `$UPSTREAM_URL`.

Finally, `$PROJECT` is the name of this project.

To setup your clone and be able to rebase when requested, run the
following commands:

[source,bash]
$ git clone $ORIGIN_URL
$ cd $PROJECT
$ git remote add upstream $UPSTREAM_URL

=== Branching

You *SHOULD* base your branch on _master_, unless your patch applies
to a stable release, in which case you need to base your branch on
the stable branch, for example _1.0.x_.

The first step is therefore to checkout the branch in question:

[source,bash]
$ git checkout 1.0.x

The next step is to update the branch to the current version from
_upstream_. In the following snippet, replace _1.0.x_ by _master_
if you are patching _master_.

[source,bash]
$ git fetch upstream
$ git rebase upstream/1.0.x

This last command may fail and ask you to stash your changes. When
that happens, run the following sequence of commands:

[source,bash]
$ git stash
$ git rebase upstream/1.0.x
$ git stash pop

The final step is to create a new branch you can work in. The name
of the new branch is up to you, there is no particular requirement.
Replace `$BRANCH` with the branch name you came up with:

[source,bash]
$ git checkout -b $BRANCH

_Your local copy_ is now ready.

=== Source editing

There are very few rules with regard to source code editing.

You *MUST* use horizontal tabs for indentation. Use one tab
per indentation level.

You *MUST NOT* align code. You can only add or remove one
indentation level compared to the previous line.

You *SHOULD NOT* write lines more than about a hundred
characters. There is no hard limit, just try to keep it
as readable as possible.

You *SHOULD* write small functions when possible.

You *SHOULD* avoid a too big hierarchy of case clauses inside
a single function.

You *SHOULD* add tests to make sure your code works.

=== Committing

You *SHOULD* run Dialyzer and the test suite while working on
your patch, and you *SHOULD* ensure that no additional tests
fail when you finish.

You can use the following command to run Dialyzer:

[source,bash]
$ make dialyze

You have two options to run tests. You can either run tests
across all supported Erlang versions, or just on the version
you are currently using.

To test across all supported Erlang versions:

[source,bash]
$ make -k ci

To test using the current version:

[source,bash]
$ make tests

You can then open Common Test logs in 'logs/all_runs.html'.

By default Cowboy excludes a few test suites that take too
long to complete. For example all the examples are built and
tested, and one Websocket test suite is very extensive. In
order to run everything, do:

[source,bash]
$ make tests FULL=1

Once all tests pass (or at least, no new tests are failing),
you can commit your changes.

First you need to add your changes:

[source,bash]
$ git add src/file_you_edited.erl

If you want an interactive session, allowing you to filter
out changes that have nothing to do with this commit:

[source,bash]
$ git add -p

You *MUST* put all related changes inside a single commit. The
general rule is that all commits must pass tests. Fix one bug
per commit. Add one feature per commit. Separate features in
multiple commits only if smaller parts of the feature make
sense on their own.

Finally once all changes are added you can commit. This
command will open the editor of your choice where you can
put a proper commit title and message.

[source,bash]
$ git commit

Do not use the `-m` option as it makes it easy to break the
following rules:

You *MUST* write a proper commit title and message. The commit
title is the first line and *MUST* be at most 72 characters.
The second line *MUST* be left blank. Everything after that is
the commit message. You *SHOULD* write a detailed commit
message. The lines of the message *MUST* be at most 80 characters.
You *SHOULD* explain what the commit does, what references you
used and any other information that helps understanding why
this commit exists. You *MUST NOT* include commands to close
GitHub tickets automatically.

=== Cleaning the commit history

If you create a new commit every time you make a change, however
insignificant, you *MUST* consolidate those commits before
sending the pull request.

This is done through _rebasing_. The easiest way to do so is
to use interactive rebasing, which allows you to choose which
commits to keep, squash, edit and so on. To rebase, you need
to give the original commit before you made your changes. If
you only did two changes, you can use the shortcut form `HEAD^^`:

[source,bash]
$ git rebase -i HEAD^^

=== Submitting the pull request

You *MUST* push your branch to your fork on GitHub. Replace
`$BRANCH` with your branch name:

[source,bash]
$ git push origin $BRANCH

You can then submit the pull request using the GitHub interface.
You *SHOULD* provide an explanatory message and refer to any
previous ticket related to this patch. You *MUST NOT* include
commands to close other tickets automatically.

=== Updating the pull request

Sometimes the maintainer will ask you to change a few things.
Other times you will notice problems with your submission and
want to fix them on your own.

In either case you do not need to close the pull request. You
can just push your changes again and, if needed, force them.
This will update the pull request automatically.

[source,bash]
$ git push -f origin $BRANCH

=== Merging

This is an open source project maintained by independent developers.
Please be patient when your changes aren't merged immediately.

All pull requests run through a Continuous Integration service
to ensure nothing gets broken by the changes submitted.

Bug fixes will be merged immediately when all tests pass.
The maintainer may do style changes in the merge commit if
the submitter is not available. The maintainer *MUST* open
a new ticket if the solution could still be improved.

New features and backward incompatible changes will be merged
when all tests pass and all other requirements are fulfilled.