Submitting Patches

How to contribute patches and packages to OpenWrt: git workflow, patch format requirements, submission methods, and the review process.

OpenWrt accepts contributions through two channels: patches sent to the development mailing list, and pull requests on the GitHub mirror. Both paths have the same quality requirements.

Before you start

Dev Mailing List

[e-mail] — the primary submission channel for patches to the main tree.

GitHub Mirror

github.com/openwrt/openwrt — pull requests are accepted and triaged here.

IRC / Matrix

#openwrt-devel on OFTC (irc.oftc.net) and the bridged Matrix room.

Bug Tracker

bugs.openwrt.org — file bugs and track issues.

Git workflow

1. Fork and clone

   Fork the repository on GitHub, then clone your fork:

   git clone https://github.com/<your-user>/openwrt.git
   cd openwrt
   git remote add upstream https://github.com/openwrt/openwrt.git
   
2. Create a topic branch

   Always work on a dedicated branch, not on main:

   git fetch upstream
   git checkout -b add-mypackage upstream/main
   
3. Make your changes

   Make one logical change per commit. Keep commits focused — reviewers evaluate each commit independently.

   # Edit files, then stage
   git add package/utils/mypackage/Makefile
   git commit
   
4. Write a good commit message

   Follow the subject line format used throughout the tree:

   <component>: <short description>
   

   For a new package:

   mypackage: add version 1.2.3
   

   For an update:

   mypackage: update to version 1.3.0
   

   For a fix:

   mypackage: fix build with musl libc
   

   The full message format:

   component: short description (imperative mood, ≤72 chars)
   
   Optional longer explanation of why the change is needed.
   Wrap body at 72 characters.
   
   Signed-off-by: Your Name <[e-mail]>
   

   The Signed-off-by line is required. It certifies that you have the right to submit the contribution under the project’s license (the Developer Certificate of Origin). Add it automatically:

   git commit --signoff
   

Patch format requirements

OpenWrt uses checkpatch.pl (adapted from the Linux kernel) to check patches:

./scripts/checkpatch.pl --no-tree 0001-mypackage-add.patch

Key requirements checked by checkpatch.pl:

Requirement	Detail
Signed-off-by	Every patch must have at least one Signed-off-by line.
Subject line	Must follow component: description format. No trailing period.
Line length	Lines in commit message body should not exceed 72 characters.
SPDX identifiers	New files must include an SPDX license header.
No trailing whitespace	Patches must not introduce trailing whitespace.
Blank line after subject	A blank line must separate the subject from the body.

SPDX license headers

All new Makefiles must include an SPDX identifier. For GPL-2.0-only (the most common OpenWrt license):

# SPDX-License-Identifier: GPL-2.0-only

For packages with a different upstream license, use the correct SPDX expression and set PKG_LICENSE accordingly:

PKG_LICENSE:=MIT
PKG_LICENSE_FILES:=LICENSE

Submitting via the mailing list

The mailing list is the authoritative submission channel for patches to the core tree.

1. Generate patches with git format-patch

   # Single patch
   git format-patch -1 HEAD
   
   # Patch series (last 3 commits)
   git format-patch -3 HEAD
   
   # Add a cover letter for a series
   git format-patch --cover-letter -3 HEAD
   

   This produces numbered .patch files: 0001-component-description.patch.

2. Check the patches

   ./scripts/checkpatch.pl 0001-*.patch
   

   Fix any reported errors or warnings before sending.

3. Send with git send-email

   git send-email \
     --to [e-mail] \
     0001-mypackage-add.patch
   

   For a series with a cover letter:

   git send-email \
     --to [e-mail] \
     --compose \
     000*.patch
   

   Configure git send-email in ~/.gitconfig:

   [sendemail]
     smtpserver = smtp.example.com
     smtpuser = [e-mail]
     smtpencryption = tls
     smtpserverport = 587
   

Submitting via GitHub pull request

For contributors who prefer a web-based workflow, pull requests on the GitHub mirror are reviewed and merged by maintainers.

# Push your branch to your fork
git push origin add-mypackage

Then open a pull request from your branch against openwrt/openwrt:main on GitHub. Apply the same commit message standards — the PR title and description do not replace a proper commit message.

GitHub PRs are triaged and merged by maintainers. For time-sensitive security fixes or large patch series, the mailing list is preferred as it reaches the widest audience of reviewers.

Patch checklist

Before submitting, verify:

Coding style

• Makefile indentation uses tabs, not spaces.
• No trailing whitespace on any line.
• Variable assignments use := for immediate expansion and = for deferred expansion — follow the pattern of surrounding code.
• INSTALL_BIN, INSTALL_DATA, INSTALL_DIR, INSTALL_CONF macros used instead of raw install or cp commands.

Package metadata

• PKG_NAME, PKG_VERSION, PKG_RELEASE are set.
• PKG_HASH or PKG_MIRROR_HASH is set and correct.
• PKG_LICENSE and PKG_LICENSE_FILES are set.
• PKG_MAINTAINER is set to your name and email.
• TITLE is a concise single-line description.
• URL points to the upstream project homepage.
• DEPENDS lists all required runtime libraries.

Build correctness

• The package builds cleanly for at least one target: make package/<name>/compile V=s.
• The package builds with make -j$(nproc) (parallel build).
• No host tools or paths are hardcoded — use $(STAGING_DIR), $(TARGET_CROSS), etc.
• Files are installed using the correct macros (INSTALL_BIN for executables, INSTALL_DATA for data files).

Licensing

• The Makefile has an SPDX header: # SPDX-License-Identifier: GPL-2.0-only.
• PKG_LICENSE uses a valid SPDX expression.
• PKG_LICENSE_FILES names the actual license file(s) within the upstream source.
• The package license is compatible with distribution in OpenWrt images.

The review and merge process

Once a patch is submitted:

1. Review — maintainers and community members review the patch on the mailing list or GitHub. Address feedback by sending a revised patch with a version suffix: [PATCH v2].
2. Staging tree — accepted patches are merged into a maintainer’s staging tree first.
3. openwrt.git — after sufficient testing, patches are merged from the staging tree into the main openwrt.git repository.
4. Notification — you receive an email when the patch is applied.

For patch revisions, include a changelog below the --- separator in the patch:

component: update to version 2.0.0

Bump to latest upstream release.

Signed-off-by: Your Name <[e-mail]>
---
Changes in v2:
- Fix PKG_HASH
- Add missing DEPENDS on libpthread

 package/utils/mypackage/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)