diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03f965f69e..29ba5dbaa9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,9 @@ (See 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 `) * 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 ) -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: ) -#### | Full Name | Identifier | |---|:---|