summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
blob: 328b9f7859a189eee2b342bf4268211ff5ef0ff9 (plain)
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
# Contributing to Erlang/OTP

## Reporting a bug

Report bugs at https://bugs.erlang.org. See [Bug reports](https://github.com/erlang/otp/wiki/Bug-reports)
for more information.

## Submitting Pull Requests

You can contribute to Erlang/OTP by opening a Pull Request.

## Fixing a bug

* In most cases, pull requests for bug fixes should be based on the `maint` branch.
There are exceptions, for example corrections to bugs that have been introduced in the `master` branch.

* Include a test case to ensure that the bug is fixed **and that it stays fixed**.

* TIP: Write the test case **before** fixing the bug so that you can know that it catches the bug.

* For applications without a test suite in the git repository, it would be appreciated if you provide a
small code sample in the commit message or email a module that will provoke the failure.

## Adding a new feature

* In most cases, pull requests for new features should be based on the `master` branch.

* It is recommended to discuss new features on
[the erlang-questions mailing list](http://erlang.org/mailman/listinfo/erlang-questions),
especially for major new features or any new features in ERTS, Kernel, or STDLIB.

* It is important to write a good commit message explaining **why** the feature is needed.
We prefer that the information is in the commit message, so that anyone that want to know 
two years later why a particular feature can easily find out. It does no harm to provide
the same information in the pull request (if the pull request consists of a single commit,
the commit message will be added to the pull request automatically).

* With few exceptions, it is mandatory to write a new test case that tests the feature.
The test case is needed to ensure that the features does not stop working in the future.

* Update the [Documentation](https://github.com/erlang/otp/wiki/Documentation) to describe the feature.

* Make sure that the new feature builds and works on all major platforms. Exceptions are features
that only makes sense one some platforms, for example the `win32reg` module for accessing the Windows registry.

* Make sure that your feature does not break backward compatibility. In general, we only break backward
compatibility in major releases and only for a very good reason. Usually we first deprecate the
feature one or two releases beforehand.

* In general, language changes/extensions require an
[EEP (Erlang Enhancement Proposal)](https://github.com/erlang/eep) to be written and approved before they 
can be included in OTP. Major changes or new features in ERTS, Kernel, or STDLIB will need an EEP or at least
a discussion on the mailing list.

## Before you submit your pull request

* Make sure existing test cases don't fail. It is not necessary to run all tests (that would take many hours),
but you should at least run the tests for the application you have changed.
See [Running tests](https://github.com/erlang/otp/wiki/Running-tests).

Make sure that your branch contains clean commits:

* Don't make the first line in the commit message longer than 72 characters.
**Don't end the first line with a period.**

* Follow the guidelines for [Writing good commit messages](https://github.com/erlang/otp/wiki/Writing-good-commit-messages).

* Don't merge `maint` or `master` into your branch. Use `git rebase` if you need to resolve merge
conflicts or include the latest changes.

* To make it possible to use the powerful `git bisect` command, make sure that each commit can be
compiled and that it works.

* Check for unnecessary whitespace before committing with `git diff --check`.

Check your coding style:

* Make sure your changes follow the coding and indentation style of the code surrounding your changes.

* Do not commit commented-out code or files that are no longer needed. Remove the code or the files.

* In most code (Erlang and C), indentation is 4 steps. Indentation using only spaces is **strongly recommended**.

### Configuring Emacs

If you use Emacs, use the Erlang mode, and add the following lines to `.emacs`:

    (setq-default indent-tabs-mode nil)
    (setq c-basic-offset 4)

If you want to change the setting only for the Erlang mode, you can use a hook like this:

```
(add-hook 'erlang-mode-hook 'my-erlang-hook)

(defun my-erlang-hook ()
  (setq indent-tabs-mode nil))
```