CONTRIBUTING.md

   1 # Contributing Guidelines
   2
   3 Ref: <https://openwrt.org/docs/guide-developer/packages> for overall format and construction
   4
   5 ## Basic guidelines
   6
   7 All packages you commit or submit by pull-request should follow these simple
   8 guidelines:
   9
  10 - Package a version which is still maintained by the upstream author and will
  11   be updated regularly with supported versions.
  12 - Have no dependencies outside the OpenWrt core packages or this repository
  13   feed.
  14 - Have been tested to compile with the correct includes and dependencies.
  15   Please also test with "Compile with full language support" found under
  16   "General Build Settings" set if language support is relevant to your package.
  17 - Best of all -- it works as expected!
  18
  19 ## Package Sources (archives and repositories)
  20
  21 - PKG_SOURCE should reference the smallest available archive. In order of
  22   preference: xz (most compressed), bzip2, gz and zip. As a last resort,
  23   downloads from source repositories can be used.
  24 - PKG_SOURCE_URL should link to an official release archive. Use of HTTPS&#x3A;
  25   is preferred. If a source archive is not available, a locally generated
  26   archive fetched using git, svn, cvs or in rare circumstances, hg or bzr.
  27 - Convenience macros for popular mirrors are defined. Using these macros will
  28   make your package downloads more robust by mapping to a list of possible
  29   source mirrors for archive availability.
  30   - @SF - SourceForge (downloads.sourceforge.net) with 5 retries due to
  31     re-directs
  32   - @GITHUB - GitHub (raw.githubusercontent.com) with 5 retries due to
  33     re-directs
  34   - @GNU - 8 regional servers
  35   - @GNOME - 8 regional servers
  36   - @SAVANNAH - 8 regional servers
  37   - @APACHE - 8 regional servers
  38   - @KERNEL - Linux kernel archives & mirrors
  39 - Please _DO NOT_ use an archive which changes over time. A version labeled
  40   "latest" is not constant each download. Also, using the head of a branch will
  41   create unpredictable results which can be different each build.
  42
  43 ### Makefile contents should contain
  44
  45 - Provide an up-to-date Copyright notice or **none**. Copyright should not be
  46   assigned to OpenWrt unless you are explicitly requested by or working under
  47   contract to OpenWrt. Assigning a Copyright to yourself or organization you
  48   represent is acceptable.
  49 - A (PKG\_)MAINTAINER definition listing either yourself and/or another person
  50   responsible for this package (E.g.: PKG_MAINTAINER:= Joe D. Hacker
  51   `<jdh@jdhs-email-provider.org`>). Listing multiple maintainers is encouraged in
  52   order to keep the package active and up-to-date. Leaving this blank will also
  53   be accepted, however the review process may not be as quick as one with a
  54   maintainer.
  55 - A PKG_LICENSE tag declaring the main license of the package.  (E.g.:
  56   PKG_LICENSE:=GPL-2.0-or-later) Please use SPDX identifiers if possible (see
  57   list at the bottom).
  58 - An optional PKG_LICENSE_FILES tag including the filenames of the
  59   license-files in the source-package.  (E.g.: PKG_LICENSE_FILES:=COPYING)
  60 - PKG_RELEASE should be initially set to 1 or reset to 1 if the software
  61   version is changed. You should increment it if the package itself has
  62   changed. For example, modifying a support script, changing configure options
  63   like --disable_ or --enable\_ switches, or if you changed something in the
  64   package which causes the resulting binaries to be different. Changes like
  65   correcting md5sums, changing mirror URLs, adding a maintainer field or updating
  66   a comment or copyright year in a Makefile do not require a change to
  67   PKG_RELEASE.
  68 - Avoid reuse of PKG_NAME in call, define and eval lines to improve
  69   readability.
  70
  71 ### Commits in your pull-requests should
  72
  73 - Have a useful commit subject prefixed with the package name (E.g.: "foopkg:
  74   Add libzot dependency").
  75 - Include Signed-off-by tag in the commit comments.  See: [Sign your
  76   work](https://openwrt.org/submitting-patches#sign_your_work)
  77 - Author and sign-off must match and be a real name or known identity and
  78   a real email address. GitHub private email addresses will not be accepted.
  79 - Follow all [Submission Guidelines](https://openwrt.org/submitting-patches#submission_guidelines)
  80   requirements, including maximum characters per line.
  81
  82 ## Advice on pull requests
  83
  84 Pull requests are the easiest way to contribute changes to git repos at GitHub.
  85 They are the preferred contribution method, as they offer a nice way for
  86 commenting and amending the proposed changes.
  87
  88 - You need a local "fork" of the GitHub repo.
  89
  90 - Use a "feature branch" for your changes. That separates the changes in the
  91   pull request from your other changes and makes it easy to edit/amend commits
  92   in the pull request. Workflow using "feature_x" as the example:
  93   - Update your local git fork to the tip (of the master, usually)
  94   - Create the feature branch with `git checkout -b feature_x`
  95   - Edit changes and commit them locally
  96   - Push them to your GitHub fork by `git push -u origin feature_x`. That
  97     creates the "feature_x" branch at your GitHub fork and sets it as the
  98     remote of this branch
  99   - When you now visit GitHub, you should see a proposal to create a pull
 100     request
 101
 102 - If you later need to add new commits to the pull request, you can simply
 103   commit the changes to the local branch and then use `git push` to
 104   automatically update the pull request.
 105
 106 - If you need to change something in the existing pull request (e.g. to add a
 107   missing signed-off-by line to the commit message), you can use `git push -f`
 108   to overwrite the original commits. That is easy and safe when using a feature
 109   branch. Example workflow:
 110   - Checkout the feature branch by `git checkout feature_x`
 111   - Edit changes and commit them locally. If you are just updating the commit
 112     message in the last commit, you can use `git commit --amend` to do that
 113   - If you added several new commits or made other changes that require
 114     cleaning up, you can use `git rebase -i HEAD~X` (X = number of commits to
 115     edit) to possibly squash some commits
 116   - Push the changed commits to GitHub with `git push -f` to overwrite the
 117     original commits in the "feature_x" branch with the new ones. The pull
 118     request gets automatically updated
 119
 120 ## If you have commit access
 121
 122 - Do NOT use git push --force.
 123 - Do NOT commit to other maintainer's packages without their consent.
 124 - Use Pull Requests if you are unsure and to suggest changes to other
 125   maintainers.
 126
 127 ### Gaining commit access
 128
 129 - We will gladly grant commit access to responsible contributors who have made
 130   useful pull requests and / or feedback or patches to this repository or
 131   OpenWrt in general. Please include your request for commit access in your next
 132   pull request or ticket.
 133
 134 ## Release Branches
 135
 136 - Old stable branches were named after the following pattern "for-XX.YY" (e.g.
 137   for-14.07) before the LEDE split.  During the LEDE split there was only one
 138   release branch with the name "lede-17.01".  After merging the LEDE fork with
 139   OpenWrt the release branches are named according to the following pattern
 140   "openwrt-XX.YY" (e.g. openwrt-18.06).
 141 - These branches are built with the respective OpenWrt release and are created
 142   during the release stabilisation phase.
 143 - Please ONLY cherry-pick or commit security and bug-fixes to these branches.
 144 - Do NOT add new packages and do NOT do major upgrades of packages here.
 145 - If you are unsure if your change is suitable, please use a pull request.
 146
 147 ## Common LICENSE tags (short list)
 148
 149 (Complete list can be found at: <https://spdx.org/licenses>)
 150
 151 | Full Name                                        | Identifier               |
 152 | ------------------------------------------------ | :----------------------- |
 153 | Apache License 1.0                               | Apache-1.0               |
 154 | Apache License 1.1                               | Apache-1.1               |
 155 | Apache License 2.0                               | Apache-2.0               |
 156 | Artistic License 1.0                             | Artistic-1.0             |
 157 | Artistic License 1.0 w/clause 8                  | Artistic-1.0-cl8         |
 158 | Artistic License 1.0 (Perl)                      | Artistic-1.0-Perl        |
 159 | Artistic License 2.0                             | Artistic-2.0             |
 160 | BSD 2-Clause "Simplified" License                | BSD-2-Clause             |
 161 | BSD 2-Clause FreeBSD License                     | BSD-2-Clause-FreeBSD     |
 162 | BSD 2-Clause NetBSD License                      | BSD-2-Clause-NetBSD      |
 163 | BSD 3-Clause "New" or "Revised" License          | BSD-3-Clause             |
 164 | BSD with attribution                             | BSD-3-Clause-Attribution |
 165 | BSD 3-Clause Clear License                       | BSD-3-Clause-Clear       |
 166 | BSD 4-Clause "Original" or "Old" License         | BSD-4-Clause             |
 167 | BSD-4-Clause (University of California-Specific) | BSD-4-Clause-UC          |
 168 | BSD Protection License                           | BSD-Protection           |
 169 | GNU General Public License v1.0 only             | GPL-1.0-only             |
 170 | GNU General Public License v1.0 or later         | GPL-1.0-or-later         |
 171 | GNU General Public License v2.0 only             | GPL-2.0-only             |
 172 | GNU General Public License v2.0 or later         | GPL-2.0-or-later         |
 173 | GNU General Public License v3.0 only             | GPL-3.0-only             |
 174 | GNU General Public License v3.0 or later         | GPL-3.0-or-later         |
 175 | GNU Lesser General Public License v2.1 only      | LGPL-2.1-only            |
 176 | GNU Lesser General Public License v2.1 or later  | LGPL-2.1-or-later        |
 177 | GNU Lesser General Public License v3.0 only      | LGPL-3.0-only            |
 178 | GNU Lesser General Public License v3.0 or later  | LGPL-3.0-or-later        |
 179 | GNU Library General Public License v2 only       | LGPL-2.0-only            |
 180 | GNU Library General Public License v2 or later   | LGPL-2.0-or-later        |
 181 | Fair License                                     | Fair                     |
 182 | ISC License                                      | ISC                      |
 183 | MIT License                                      | MIT                      |
 184 | No Limit Public License                          | NLPL                     |
 185 | OpenSSL License                                  | OpenSSL                  |
 186 | X11 License                                      | X11                      |
 187 | zlib License                                     | Zlib                     |
 188
 189 ## Continuous Integration
 190
 191 To simplify review and require less human resources, a CI tests all packages.
 192 Passing CI tests are not a hard requirement but a good indicator what the
 193 Buildbots will think about the proposed patch.
 194
 195 The CI builds modified packages for multiple architectures using the latest
 196 snapshot SDK. For supported architectures (`aarch64_generic`,
 197 `arm_cortex-a15_neon-vfpv4`, `i386_pentium4` and `x86_64`) an additional
 198 runtime test is executed. A running OpenWrt is simulated which tries to install
 199 created packages and runs a script called `test.sh` located next to the package
 200 Makefile. The script is executed with the two arguments `PKG_NAME` and
 201 `PKG_VERSION`. The `PKG_NAME` can be used to distinguish package variants, e.g.
 202 `foobar` vs. `foobar-full`. The `PKG_VERSION` can be used for a trivial test
 203 checking if `foobar --version` prints the correct version. `PKG_VERSION` is the
 204 OpenWrt version and therefore includes the `PKG_RELEASE`, which isn't usually
 205 part of the running programs version.
 206
 207 The following snippet shows a script that tests different binaries depending on
 208 what IPK package was installed. The `gpsd` Makefile produces both a `gpsd` and
 209 a `gpsd-clients` IPK packages.
 210
 211 ```shell
 212  #!/bin/sh
 213
 214 case "$1" in
 215     "gpsd")
 216         gpsd -V 2>&1 | grep "$2"
 217         ;;
 218     "gpsd-clients")
 219         cgps -V 2>&1 | grep "$2"
 220         ;;
 221 esac
 222 ```