Skip to content

Commit d2fc624

Browse files
LourensPoolcmaglie
authored andcommitted
Add CONTRIBUTING.md to root folder
1 parent e202d2e commit d2fc624

File tree

1 file changed

+65
-0
lines changed

1 file changed

+65
-0
lines changed

CONTRIBUTING.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
## Contributing guide
2+
A simple four step guide to consider when you want your pull request to be merged without a hassle. This guide mainly focusses on the proper use of Git. It has some overlap with the more general information found in the [Development Policy File](https://github.com/arduino/Arduino/wiki/Development-Policy).
3+
4+
### 1. Bugs and small enhancements
5+
To report a bug or a small enhancement please use the [issue tracker](http://github.com/arduino/Arduino/issues).
6+
7+
### 2. Larger changes
8+
Before starting to work on bigger topics like modifying the API or changes with backward compatibility trade-offs please discuss them in the [mailing list](https://groups.google.com/a/arduino.cc/forum/#!forum/developers) first.
9+
10+
### 3. Commit messages
11+
An easy to read pull request will speed up the merging process. Your commit messages need to be logically separate. And containing enough information on their own. When this is done consistently your pull request will have an easy to read log of changes.
12+
13+
If you did not read the following 7 points before or just want to fresh up. Please read up on them on this [website](https://chris.beams.io/posts/git-commit) by Chris Beams.
14+
15+
1. Separate subject from body with a blank line
16+
2. Limit the subject line (first line) to 50 characters
17+
3. Capitalize the subject line
18+
4. Do not end the subject line with a period `(.)`
19+
5. Use the imperative mood in the subject line.
20+
This should be in the written as giving an instruction for example "update getting started documentation" (it shows what the PR achieves when merging it)
21+
6. Wrap body at 72 characters
22+
7. Use the body to explain what, why and how
23+
24+
A general example with these 7 guidelines in mind is shown below (from the same website of [Chris Beams](https://chris.beams.io/posts/git-commit)):
25+
```
26+
Summarize changes in around 50 characters or less
27+
28+
More detailed explanatory text, if necessary. Wrap it to about 72
29+
characters or so. In some contexts, the first line is treated as the
30+
subject of the commit and the rest of the text as the body. The
31+
blank line separating the summary from the body is critical (unless
32+
you omit the body entirely); various tools like `log`, `shortlog`
33+
and `rebase` can get confused if you run the two together.
34+
35+
Explain the problem that this commit is solving. Focus on why you
36+
are making this change as opposed to how (the code explains that).
37+
Are there side effects or other unintuitive consequences of this
38+
change? Here's the place to explain them.
39+
40+
Further paragraphs come after blank lines.
41+
42+
- Bullet points are okay, too
43+
44+
- Typically a hyphen or asterisk is used for the bullet, preceded
45+
by a single space, with blank lines in between, but conventions
46+
vary here
47+
48+
If you use an issue tracker, put references to them at the bottom,
49+
like this:
50+
51+
Resolves: #123
52+
See also: #456, #789
53+
```
54+
55+
### 4. Rebasing pull requests
56+
When different people are working on the Arduino project simultaneously, pull requests can go stale quickly. A "stale" pull request is one that is no longer up to date with the latest merges in the project. It needs to be updated before it can be merged.
57+
58+
Most often pull requests become stale when merge conflicts occur. This happens when two pull requests both modify similar lines in the same file and one gets merged, the unmerged request will now have a merge conflict and needs updating.
59+
60+
When your pull request is stale, you will need to rebase your branch on the current master branch before you can merge it without conflicts.
61+
62+
More information about rebasing can be found at the repository of edX, [here](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request).
63+
64+
### 5. Merged!
65+
If you followed the previous four steps. Your pull request will be merged faster!

0 commit comments

Comments
 (0)