CONTRIBUTING.md: Add advice about pull requests

Add "best practices" advice about working with pull requests.

Signed-off-by: Hannu Nyman <hannu.nyman@iki.fi>
(cherry picked from commit df35777400041367e6696729a22e6e0295e930bf)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 03f965f69e93412d03afc9d07d5c5d37a0ba44e2..29ba5dbaa9eab437bce9db6f4314486f08fbb1bd 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,8 +2,9 @@
 (See <http://wiki.openwrt.org/doc/devel/packages> for overall format and construction)
 
 
-All packages you commit or submit by pull-request should follow these simple guidelines:
+### Basic guidelines
 
+All packages you commit or submit by pull-request should follow these simple guidelines:
 * Package a version which is still maintained by the upstream author.
 * Will be updated regularly to maintained and supported versions.
 * Have no dependencies outside the OpenWrt core packages or this repository feed.
@@ -11,10 +12,10 @@ All packages you commit or submit by pull-request should follow these simple gui
 * Do NOT use a rolling source file (e.g. foo-latest.tar.gz) or the head of a branch as source for the package since that would create unpredictable builds which change over time.
 * Best of all -- it works as expected!
 
-Makefile contents should contain:
+#### Makefile contents should contain:
 
 * An up-to-date copyright notice. Use OpenWrt if no other present or supply your own.
-* A (PKG_)MAINTAINER definition listing either yourself or another person in the field.  
+* A (PKG_)MAINTAINER definition listing either yourself or another person in the field.
     (E.g.: PKG_MAINTAINER:= Joe D. Hacker `<jdh@jdhs-email-provider.org`>)
 * A PKG_LICENSE tag declaring the main license of the package.
     (E.g.: PKG_LICENSE:=GPL-2.0+) Please use SPDX identifiers if possible (see list at the bottom).
@@ -22,27 +23,47 @@ Makefile contents should contain:
     (E.g.: PKG_LICENSE_FILES:=COPYING)
 * PKG_RELEASE should be initially set to 1 or reset to 1 if the software version is changed. You should increment it if the package itself has changed. For example, modifying a support script, changing configure options like --disable* or --enable* switches, or if you changed something in the package which causes the resulting binaries to be different. Changes like correcting md5sums, changing mirror URLs, adding a maintainer field or updating a comment or copyright year in a Makefile do not require a change to PKG_RELEASE.
 
-Commits in your pull-requests should:
+#### Commits in your pull-requests should:
 
-* Have a useful description prefixed with the package name  
+* Have a useful description prefixed with the package name
     (E.g.: "foopkg: Add libzot dependency")
-* Include Signed-off-by in the comment  
+* Include Signed-off-by in the comment
     (See <https://dev.openwrt.org/wiki/SubmittingPatches#a10.Signyourwork>)
 
-If you have commit access:
+### Advice on pull requests:
+
+Pull requests are the easiest way to contribute changes to git repos at Github. They are the preferred contribution method, as they offer a nice way for commenting and amending the proposed changes.
+
+* You need a local "fork" of the Github repo.
+* Use a "feature branch" for your changes. That separates the changes in the pull request from your other changes and makes it easy to edit/amend commits in the pull request. Workflow using "feature_x" as the example:
+  - Update your local git fork to the tip (of the master, usually)
+  - Create the feature branch with `git checkout -b feature_x`
+  - Edit changes and commit them locally
+  - Push them to your Github fork by `git push -u origin feature_x`. That creates the "feature_x" branch at your Github fork and sets it as the remote of this branch
+  - When you now visit Github, you should see a proposal to create a pull request
+
+* If you later need to add new commits to the pull request, you can simply commit the changes to the local branch and then use `git push` to automatically update the pull request.
+
+* If you need to change something in the existing pull request (e.g. to add a missing signed-off-by line to the commit message), you can use `git push -f` to overwrite the original commits. That is easy and safe when using a feature branch. Example workflow:
+  - Checkout the feature branch by `git checkout feature_x`
+  - Edit changes and commit them locally. If you are just updating the commit message in the last commit, you can use `git commit --amend` to do that
+  - If you added several new commits or made other changes that require cleaning up, you can use `git rebase -i HEAD~X` (X = number of commits to edit) to possibly squash some commits
+  - Push the changed commits to Github with `git push -f` to overwrite the original commits in the "feature_x" branch with the new ones. The pull request gets automatically updated
+
+### If you have commit access:
 
 * Do NOT use git push --force.
 * Do NOT commit to other maintainer's packages without their consent.
 * Use Pull Requests if you are unsure and to suggest changes to other maintainers.
 
-Gaining commit access:
+#### Gaining commit access:
 
 * We will gladly grant commit access to responsible contributors who have made
   useful pull requests and / or feedback or patches to this repository or
   OpenWrt in general. Please include your request for commit access in your
   next pull request or ticket.
 
-Release Branches:
+### Release Branches:
 
 * Branches named "for-XX.YY" (e.g. for-14.07) are release branches.
 * These branches are built with the respective OpenWrt release and are created
@@ -51,9 +72,8 @@ Release Branches:
 * Do NOT add new packages and do NOT do major upgrades of packages here.
 * If you are unsure if your change is suitable, please use a pull request.
 
-####Common LICENSE tags (short list)  
+### Common LICENSE tags (short list)  
 (Complete list can be found at: <http://spdx.org/licenses>)
-####  
 
 | Full Name | Identifier  |
 |---|:---|