User Tools

Site Tools


Submitting patches

See first Development FAQ and How to Get Your Change Into OpenWrt.

Patches can be submitted as a pull request on Github or via the mailing list.

Submissions should follow the following guidelines:

  • use a different git branch for each pull request (GitHub does this automatically if you edit files through the website)
  • write commit subject and message in the imperative form: “add support for X”, NOT “added support for X”
  • code formatting
    • use the same indentation you find in the file you are modifying, use only tabs or only spaces depending on what was done in the rest of the file
    • entries in lists should be placed in alphabetical order
  • commit subject
    • must have a prefix that depends from what you are doing in the commit
      • kernel: for kernel and kmod (kernel module) packages
      • package name: for packages
      • device architecture: for devices (for example, mvebu: or ramips: add support to example_eval board )
      • tool name: for tools
      • build: for general buildsystem changes that are not targeted at something in /toolchain
    • must be less than 50 characters long
    • must describe what the commit changes and why the commit is necessary.
      It is challenging to be both succinct and descriptive, but that is what a well-written summary should do
    • don't capitalize first word after the prefix
    • don't write a full stop at the end of the subject line
  • commit description
    • must have less than 75 characters per line
    • it will be committed to the source changelog, so it should explain to a competent reader why you made this commit.
      Include symptoms of the failure you are fixing (log messages, error messages, etc.), it will be useful for
      people searching the commit logs looking for a fix for their issue.
      If a patch fixes a compile failure, include only the most relevant part of the failure log
    • If you add support for new hardware: Include in your commit message a short description of the hardware and how to install OpenWrt on it. Have a look at the recent additions for some examples.
  • all commits must contain Signed-off-by: My Name <my@email.address> where you write your real name and real email address, in accordance with Section 11 of the Linux Kernel patches guide.
    • it can be done automatically by git commandline with:
      git commit --signoff
  • the Author field must match the “Signed-off-by:” line
    • if you are editing files and committing through GitHub, you must write your real name in the “Name” field in GitHub settings and the email used in the “Signed-off-by:” must be your primary github email
    • if you are editing files and committing on your local PC, set your name and email with
      git config --global "my name"
      git config --global "my@email.address"

Working with Github

There are Github mirrors of the source repository here.
Fork the project to a public repo using Github web interface, clone the repo to your computer, create a branch for your changes, push these back to Github and submit a pull request.

In case you don't know how to do that, keep reading.

Create a Github account, this will host your public fork of LEDE source, and will be used for all interaction on Github.

Install git in your PC, and make sure that your local git settings have the right name and email

git config --global "my name"
git config --global "my@email.address"

You might also want to set the default text editor to your favourite editor. If you have a Linux system with a GUI, some choices are geany, kwrite, pluma and gedit.
If you are using command line, nano is a good one.

git config --global core.editor "editor-name-here"

Then follow Github's excellent documentation to Fork A Repo and Create a local clone of your fork

After you have set it up as described, write

git checkout -b my-new-branch-name

to create a branch for your PR (“my-new-branch-name” is just an example name, use a more descriptive name in yours).
All commits you do after this command will be grouped in this branch. This allows to have multiple branches, one for each PR.
To switch between branches you already created, use

git checkout my-branch-name

After you made your changes, write

git add -i

and use its interface to add untracked (new) files and update existing ones.

Then write

git commit --signoff

This will open the git default editor and you can write the commit message.
The first line is the commit subject,
then leave an empty line
then you write the commit description.
This command will automatically add the Signed-off-by line with your name and email as set above.
For example, a complete commit message might look like this:

The best code update.

This is the best piece of code I have ever submitted.
Signed-off-by: John Doe <>

To send your local changes over to your Github repo, write

git push --all

You will be asked your github user and password in the process.

After the code has been uploaded to your github repo, you can submit PR using Github web interface, see again Github's documentation about Creating a pull request

Sending patches by Email

Send an email to the development mailing list. All patches need to be sent in the same format as those that are listed on patchwork. If the patch does not get listed in patchwork then it won't get processed. Using git send-email is warmly recommended, as email clients tend to add spaces and screw up the formatting or add non-printable characters.

Squashing commits

Commits in a PR or sent by email should be about full changes you want to merge, not about fixing all issues the reviewers found in your original PR.

So, there will come a time when you will need to either rewrite or squash your commits; so you end with a normal amount of true and sane commits.

Work with git commandline.
Change to your development folder.
Look at the branches you have with:

git branch -a

get something like:

* master

Switch to the your development branch for this PR with:

git checkout best_code_update

Look at the git log, so you can count the number of commits you want to squash ( the “X” below ) with:

git log

Delete commits with:

git reset HEAD~X

(where X is the number of commits you want to delete, counted from the last commit), this will not change modified files, it will only delete the commits.
Add the files to git tracking again with:

git add -i

and commit again with:

git commit --signoff

Send the updated branch over to github with:

git push -f

and the commits in the PR will be updated automatically.

Alternative squashing advice:

You can use interactive rebase to combine, reorder and edit your commits and their commit messages, with:

git rebase -i HEAD~X

(X = number of commits to edit)

Patch Merging And Tree Life Cycle

We encourage frequent committers to host their own staging trees where they aggregate patches that they feel responsible for and/or ones that they created themselves. Once the tree has been reviewed and tested it can be proposed for inclusion in the master branch.

  1. Trees will be merged into master at any time
  2. Bug fixes can be merged into master directly
  3. PRs can be sent to the patches mailing list from any source and will always be considered for inclusion if the quality of the tree is good and format of submission is correct
  4. Staging trees can be hosted as part of the projects git infrastructure, private servers, GitHub …

Patch Checklist

  1. Single commit ( multiple commits must first be squashed, as described above )
  2. Subject < 50 characters
  3. Blank line after subject
  4. Each line of description < 75 characters
  5. Description explains what was changed
  6. Description explains why it was changed
  7. Description makes sense
  8. Signoff line includes real name
  9. Signoff line includes real email address
  10. If it's a third-party patch, then preserve Signoff line from the original author
  11. Sender/Author name and email address matches Signoff line's real name and email address

DTS Checklist

  1. Don't forget to add proper license, consider adding SPDX-License-Identifier: GPL-2.0-or-later OR MIT (details)
  2. Remove all ocurrencies of default-state = “off” properties under your LED nodes (details)
  3. If you're adding MTD flash layout, and you've label = “firmware” or a node with the name firmware@xyz, please check that you've added proper compatible property (if applicable) (details)
  4. If it's possible try to dedicate some of the LEDs for system status indication in (example)
  5. The name of a node should reflect the function of the device and not its model. Examples for generic node names can be found in Section 2.2.2 Generic Names Recommendation
  6. Remove all deprecated "device_type" properties, unless for “memory” or “cpu” nodes
submitting-patches.txt · Last modified: 2018/12/23 18:27 by chunkeey