path: root/CONTRIBUTING.md

# Contributing Guidelines

Ref: <https://openwrt.org/docs/guide-developer/packages> for overall format and construction

## 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 and will
  be updated regularly with supported versions.
- Have no dependencies outside the OpenWrt core packages or this repository
  feed.
- The compilation has been successfully tested with the appropriate includes and dependencies.
  Additionally, if language support is relevant to your package, please enable the "Compile with full language support" option found under "Global Build Settings" in "menuconfig" and conduct further tests.
- Most important -- the packaged software is tested to work as expected!

### Pointers to the guidelines the LLM reviewers use

If you have questions about what is expected of a pull request, and there is
no specific documentation for your case, or the comments from a reviewer seem
at odds with the documentation you have found, it can be useful to refer to the
prompts given to the automated LLM reviewer.

- [Project-wide LLM review guidelines](https://github.com/openwrt/actions-shared-workflows/tree/main/llm-review-prompts)
- [Packages repository-specific LLM review addendum](https://github.com/openwrt/packages/blob/master/.github/llm-review-rules.md)

## Package Sources (archives and repositories)

- <strong>PKG_SOURCE</strong> should reference the smallest available archive. In order of
  preference:
  1. xz (most compressed),
  1. bzip2, gz and zip.
  1. As a last resort downloads from source repositories can be used.
- <strong>PKG_SOURCE_URL</strong> should link to an official release archive. Use of `https://`
  is preferred.

  If a source archive is not available, a locally generated
  archive fetched using git, svn, cvs or in rare circumstances, hg or bzr.
- Convenience macros for popular mirrors are defined. Using these macros will
  make your package downloads more robust by mapping to a list of possible
  source mirrors for archive availability.
  - `@SF` - SourceForge (downloads.sourceforge.net) with 5 retries due to
    re-directs
  - `@GITHUB` - GitHub (raw.githubusercontent.com) with 5 retries due to
    re-directs
  - `@GNU` - 8 regional servers
  - `@GNOME` - 8 regional servers
  - `@SAVANNAH` - 8 regional servers
  - `@APACHE` - 8 regional servers
  - `@KERNEL` - Linux kernel archives & mirrors
- Please _DO NOT_ use an archive which changes over time. A version labeled
  "latest" is not constant each download. Also, using the head of a branch will
  create unpredictable results which can be different each build.

### Makefile contents should contain

- Provide an up-to-date Copyright notice or **none**. Copyright should not be
  assigned to OpenWrt unless you are explicitly requested by or working under
  contract to OpenWrt. Assigning a Copyright to yourself or organization you
  represent is acceptable.
- A (PKG\_)MAINTAINER definition listing either yourself and/or another person
  responsible for this package (E.g.: `PKG_MAINTAINER:= Joe D. Hacker
  <jdh@jdhs-email-provider.org>`). Listing multiple maintainers is encouraged in
  order to keep the package active and up-to-date. Leaving this blank will also
  be accepted, however the review process may not be as quick as one with a
  maintainer.
- A <strong>PKG_LICENSE</strong> tag declaring the main license of the package.  (E.g.:
  PKG_LICENSE:=GPL-2.0-or-later) Please use SPDX identifiers if possible (see
  list at the bottom).
- An optional <strong>PKG_LICENSE_FILES</strong> tag including the filenames of the
  license-files in the source-package.  (E.g.: PKG_LICENSE_FILES:=COPYING)
- <strong>PKG_RELEASE</strong> 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.
- Avoid reuse of <strong>PKG_NAME</strong> in call, define and eval lines to improve
  readability.

### Patches

Patches live in `<package>/patches/`, are managed with quilt, and are expected
in a specific shape. A patch that applies cleanly can still be sent back, so it
is worth getting all three parts right before opening the pull request.

#### Header

A patch that a pull request adds or changes needs a `git am` compatible
header, so that it can be applied to an upstream tree without editing. All four
lines are required, and their absence is a hard failure in the formality check.
Much of the tree predates that check and lacks them, so a neighbouring patch is
not a safe model to copy:

```
From <hash> Mon Sep 17 00:00:00 2001
From: Joe D. Hacker <jdh@jdhs-email-provider.org>
Date: Tue, 9 Jun 2026 04:33:35 +0000
Subject: [PATCH] setup.py: fix cross-compilation on macOS hosts
```

The `Mon Sep 17 00:00:00 2001` date is a fixed sentinel `git format-patch`
emits verbatim — do not replace it with a real date. `Date:` is the one most
often left out.

#### Body

Below the header, before the diff, explain what the patch changes and why, and
end with a `Signed-off-by` line matching the author.

Say where the change stands with respect to upstream. If it has been sent
upstream, or is a backport, link the issue, pull request or commit; an
`Upstream-Status:` line is also fine. If it will never go upstream — a
cross-compile fix, a toolchain or path adjustment, a musl workaround — say so
and why. The patch file is the only place a later maintainer will look when
deciding whether a version bump has made it redundant.

This is not a demand for prose on every patch. A one- or two-line change whose
intent is obvious from the diff needs only a subject, and a patch with no
upstream to go to needs no reference.

#### Refreshing

Always generate and update the diff with the buildroot's `refresh` target,
never by hand and never with `git diff` or `git format-patch`:

```
make package/foopkg/{clean,prepare} QUILT=1
make package/foopkg/refresh
```

`refresh` only works on a build directory that was unpacked under quilt; on one
left over from an ordinary build it stops with "The source directory was not
unpacked using quilt". The first command is what puts it in that state.

It runs quilt as
`QUILT_DIFF_OPTS="-p" quilt refresh -p ab --no-index --no-timestamps`, and each
of those options matters:

- `-p ab` gives the usual `a/` and `b/` path prefixes.
- `--no-index` drops the `Index:` line, which carries no information here.
- `--no-timestamps` drops the timestamps from the `---` and `+++` lines. They
  are the working copy's mtimes, so leaving them in makes an otherwise
  unchanged patch differ between contributors and produces a noisy diff on
  every refresh.
- `QUILT_DIFF_OPTS="-p"` passes `-p` to `diff`, so each `@@` hunk header names
  the enclosing function or section. This is what makes a patch readable in
  review, and it is the difference most often missed.

The target preserves whatever header and description already sit above the
diff, so refreshing an existing patch will not cost you its text.

### Commits in your pull-requests should

- Have a useful commit subject prefixed with the package name (E.g.: `foopkg:
  add libzot dependency`).
- Include Signed-off-by tag in the commit comments.  See: [Sign your
  work](https://openwrt.org/submitting-patches#sign_your_work)
- Author and sign-off must match and be a real name and real email address.
  GitHub private email addresses will not be accepted.
- Follow all [Submission Guidelines](https://openwrt.org/submitting-patches#submission_guidelines)
  requirements, including maximum characters per line.

## 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

- 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

- Old stable branches were named after the following pattern "for-XX.YY" (e.g.
  for-14.07) before the LEDE split. During the LEDE split there was only one
  release branch with the name "lede-17.01". After merging the LEDE fork with
  OpenWrt the release branches are named according to the following pattern
  "openwrt-XX.YY" (e.g. `openwrt-18.06`).
- These branches are built with the respective OpenWrt release and are created
  during the release stabilization phase.
- Please ONLY cherry-pick or commit security and bug-fixes to these 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)

(Complete list can be found at: <https://spdx.org/licenses>)

| Full Name                                        | Identifier               |
| ------------------------------------------------ | :----------------------- |
| Apache License 1.0                               | Apache-1.0               |
| Apache License 1.1                               | Apache-1.1               |
| Apache License 2.0                               | Apache-2.0               |
| Artistic License 1.0                             | Artistic-1.0             |
| Artistic License 1.0 w/clause 8                  | Artistic-1.0-cl8         |
| Artistic License 1.0 (Perl)                      | Artistic-1.0-Perl        |
| Artistic License 2.0                             | Artistic-2.0             |
| BSD 2-Clause "Simplified" License                | BSD-2-Clause             |
| BSD 2-Clause FreeBSD License                     | BSD-2-Clause-FreeBSD     |
| BSD 2-Clause NetBSD License                      | BSD-2-Clause-NetBSD      |
| BSD 3-Clause "New" or "Revised" License          | BSD-3-Clause             |
| BSD with attribution                             | BSD-3-Clause-Attribution |
| BSD 3-Clause Clear License                       | BSD-3-Clause-Clear       |
| BSD 4-Clause "Original" or "Old" License         | BSD-4-Clause             |
| BSD-4-Clause (University of California-Specific) | BSD-4-Clause-UC          |
| BSD Protection License                           | BSD-Protection           |
| GNU General Public License v1.0 only             | GPL-1.0-only             |
| GNU General Public License v1.0 or later         | GPL-1.0-or-later         |
| GNU General Public License v2.0 only             | GPL-2.0-only             |
| GNU General Public License v2.0 or later         | GPL-2.0-or-later         |
| GNU General Public License v3.0 only             | GPL-3.0-only             |
| GNU General Public License v3.0 or later         | GPL-3.0-or-later         |
| GNU Lesser General Public License v2.1 only      | LGPL-2.1-only            |
| GNU Lesser General Public License v2.1 or later  | LGPL-2.1-or-later        |
| GNU Lesser General Public License v3.0 only      | LGPL-3.0-only            |
| GNU Lesser General Public License v3.0 or later  | LGPL-3.0-or-later        |
| GNU Library General Public License v2 only       | LGPL-2.0-only            |
| GNU Library General Public License v2 or later   | LGPL-2.0-or-later        |
| Fair License                                     | Fair                     |
| ISC License                                      | ISC                      |
| MIT License                                      | MIT                      |
| No Limit Public License                          | NLPL                     |
| OpenSSL License                                  | OpenSSL                  |
| X11 License                                      | X11                      |
| zlib License                                     | Zlib                     |

## Continuous Integration

To simplify review and require less human resources, a CI tests all packages.
Passing CI tests are not a hard requirement but a good indicator what the
Buildbots will think about the proposed patch.

The CI builds modified packages for multiple
architectures using the latest snapshot SDK. For supported architectures
(`aarch64_generic`, `arm_cortex-a15_neon-vfpv4`, `i386_pentium-mmx`,
`mips_24kc` and `x86_64`) an additional runtime test is executed inside a
Docker container with QEMU user-mode emulation, simulating a running OpenWrt
system.

### Generic tests

The CI automatically runs a set of **generic tests** on every installed
package:

- **Executable check** — verifies that files installed in standard executable
  paths (`/usr/bin/`, `/usr/sbin/`, etc.) are actually executable.
- **Version check** — attempts to detect the package version by running each
  executable with common flags (`--version`, `-V`, `--help`, etc.) and checking
  the output for `PKG_VERSION`.
- **Hardcoded path check** — scans ELF binaries for leftover build directory
  paths (`/build_dir/`).
- **Strip check** — warns if ELF binaries are not stripped.
- **Linked library check** — verifies that all shared library dependencies are
  present on the system.
- **SONAME check** — for libraries in standard library paths, verifies that the
  SONAME is set correctly and the corresponding symlink exists.

### Test scripts

In addition to the generic tests, package maintainers can provide up to three
optional shell scripts placed next to the package Makefile:

#### `test.sh` — Functional test

A package-specific functional test script that runs **in addition** to the
generic tests. This is useful for verifying functionality that the generic
checks cannot cover (e.g. importing a Python module, encrypting/decrypting
data, or testing a specific command-line workflow). The following environment
variables are available:

| Variable      | Description                                            |
| ------------- | ------------------------------------------------------ |
| `PKG_NAME`    | Package name including variant (e.g. `foobar-full`)    |
| `PKG_VERSION` | Upstream version without the OpenWrt release suffix    |
| `CI_HELPERS`  | Path to `ci_helpers.sh` providing colored output utils |

The following snippet shows a script that tests different binaries depending on
what package was installed. The `gpsd` Makefile produces both a `gpsd` and
a `gpsd-clients` package.

```shell
#!/bin/sh

case "$1" in
    "gpsd")
        gpsd -V 2>&1 | grep "$2"
        ;;
    "gpsd-clients")
        cgps -V 2>&1 | grep "$2"
        ;;
esac
```

#### `test-version.sh` — Version check override

When the generic version check cannot detect the version automatically (e.g.
the binary does not support `--version` or reports it in a non-standard way),
a `test-version.sh` script can override the version check logic. When this
script is present, the generic version detection is skipped entirely and the
script is responsible for verifying the version.

The script receives `PKG_NAME` and `PKG_VERSION` as environment variables and
should use a `case` statement to handle individual sub-packages. Packages that
have no executable or cannot report their version should `exit 0`. Unknown
packages should `exit 1`.

```shell
#!/bin/sh

# shellcheck shell=busybox

case "$PKG_NAME" in
tor)
    tor --version | grep -F "$PKG_VERSION"
    ;;
tor-geoip)
    # Data-only package, no version to check
    exit 0
    ;;
*)
    echo "Untested package: $PKG_NAME" >&2
    exit 1
    ;;
esac
```

#### `pre-test.sh` — Pre-test setup

A script that runs **before** the package is installed. This can be used to
install additional dependencies required for testing that are not part of the
package itself.

```shell
#!/bin/sh
apk add openssl-util
```