From 037a6725fb003d3c98082b190b4d2cbe764fed37 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 7 Jun 2017 03:07:02 -0700 Subject: [PATCH] Separate CONTRIBUTING.md into Issues and Pull Requests sections The previous numbered format of the file made it difficult to determine which sections needed to be read depending on whether an issue report or a pull request was being submitted. This could make the task of reading the file look more daunting than it actually was. Closes #3368 --- CONTRIBUTING.md | 62 +++++++++++++++++-------------------------------- 1 file changed, 21 insertions(+), 41 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4b6b1e8d..1cb23ad28 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,7 @@ -## Contributing guide +# Contributing guide This document serves as a checklist before contributing to this repository. It includes includes links to read up on if topics are unclear to you. -This guide mainly focuses 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). - -### 1. Before using the issue tracker +## Issues To report a bug or a small enhancement please use the [issue tracker](http://github.com/arduino/Arduino/issues). But check the following boxes before posting an issue: - [ ] `Your issue is NOT a question about an Arduino sketch.` Sketch questions are handled on the [Arduino Forum](http://forum.arduino.cc/). @@ -25,7 +23,6 @@ To report a bug or a small enhancement please use the [issue tracker](http://git |[Arduino's build of AVRDUDE](https://github.com/arduino/avrdude-build-script)|| |Third party repository | for third party libraries, hardware packages or sketches | -### 2. Posting the issue When you have checked the previous boxes. Please consider the following points before posting the issue. - [ ] `Describe the issue based on the behaviour you were expecting` @@ -34,28 +31,22 @@ When you have checked the previous boxes. Please consider the following points b - [ ] `Demonstration code should be complete, correct and the minimum amount necessary to reproduce the issue` - [ ] `Library Manager submissions: make sure your library meets all the requirements listed in the` [Library Manager FAQ](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) -### 3. Pull Requests -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. +## Pull Requests +This guide mainly focuses 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). -### 4. Commit messages -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. - -Your commits need to be [atomic](https://www.freshconsulting.com/atomic-commits/) which allows the repository to remain flexible after merging. - -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. - -1. Separate subject from body with a blank line -2. Limit the subject line (first line) to 50 characters -3. Capitalize the subject line -4. Do not end the subject line with a period `(.)` -5. Use the imperative mood in the subject line. -This should be in the written as giving an instruction for example "Fixed save-as bug" (it shows what the PR achieves when merging it) -6. Wrap body at 72 characters -7. Use the body to explain what, why and how - -If your pull request fixes, closes or resolves an issue please reference it in the body with the following [syntax](https://help.github.com/articles/closing-issues-via-commit-messages/). Also see the last lines of the following example. - -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)): +- 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. +- 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. +- Your commits need to be [atomic](https://www.freshconsulting.com/atomic-commits/) which allows the repository to remain flexible after merging. +- 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. + - Separate subject from body with a blank line + - Limit the subject line (first line) to 50 characters + - Capitalize the subject line + - Do not end the subject line with a period `(.)` + - Use the imperative mood in the subject line. This should be in the written as giving an instruction for example "Fixed save-as bug" (it shows what the PR achieves when merging it) + - Wrap body at 72 characters + - Use the body to explain what, why and how +- If your pull request fixes, closes or resolves an issue please reference it in the body with the following [syntax](https://help.github.com/articles/closing-issues-via-commit-messages/). Also see the last lines of the following example. +- 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)): ``` Summarize changes in around 50 characters or less @@ -85,18 +76,7 @@ like this: Resolves: #123 See also: #456, #789 ``` - -### 5. Rebasing pull requests -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. - -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. - -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. - -More information about rebasing can be found at the repository of [edX](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request). - -### 6. Merged! -When your pull request is merged please update the documentation if the changes require it: - -- [ ] Edit appropiate [Wiki pages](https://github.com/arduino/Arduino/wiki/_pages) -- [ ] Submit an [issue report](https://github.com/arduino/Arduino/issues/new) requesting changes to the [arduino.cc reference pages](https://www.arduino.cc/en/Reference/HomePage) +- 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. 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. 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. More information about rebasing can be found at the repository of [edX](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request). +- When your pull request is merged please update the documentation if the changes require it: + - [ ] Edit appropiate [Wiki pages](https://github.com/arduino/Arduino/wiki/_pages) + - [ ] Submit an [issue report](https://github.com/arduino/Arduino/issues/new) requesting changes to the [arduino.cc reference pages](https://www.arduino.cc/en/Reference/HomePage)