path: root/README

About the send-patches.org Patch Repository
-------------------------------------------

This repository contains patches for other open source projects which
are necessary to make them more cross-compiling friendly. The cross
build community has a long history of carrying patches arround, but
trust us - we do all hate them :-)

Help us make the upstream better and create more awareness for cross
compile issues!

- The send-patches.org team


Patch Guidelines
----------------

The following checklist should make it easier for you to find out if a
patch contains all necessary information:

[ ] Is the patch documented using the Linux kernel's "canonical patch"
    format [1]?

[ ] The patch must contain a subject line (like an email subject),
    stating clearly what the patch does. Example:

    makefile: fix cross compile issues

[ ] Check if the subject line is descriptive enough to understand the
    patch, even if you wouldn't already know what it does :) Add a
    descriptive text to the body if the subject alone isn't enough.

[ ] Document what the issue is that is being fixed. If the patch fixes
    a build error, add the error output. This makes it easier for
    other people to find our patch with their favourite serach engine.

[ ] Document why the patch is necessary. Especially if the patch fixes a
    cross compile speciality, not everyone in the open source community
    might be aware of the background


Signing Patches
---------------

With a line saying

Signed-off-by: Joe Hacker <joe@send-patches.org>

a contributor states that he is following the rules. We use the same
definition as the Linux kernel, which is re-printed here:

        Developer's Certificate of Origin 1.1

        By making a contribution to this project, I certify that:

        (a) The contribution was created in whole or in part by me and I
            have the right to submit it under the open source license
            indicated in the file; or

        (b) The contribution is based upon previous work that, to the best
            of my knowledge, is covered under an appropriate open source
            license and I have the right under that license to submit that
            work with modifications, whether created in whole or in part
            by me, under the same open source license (unless I am
            permitted to submit under a different license), as indicated
            in the file; or

        (c) The contribution was provided directly to me by some other
            person who certified (a), (b) or (c) and I have not modified
            it.

        (d) I understand and agree that this project and the contribution
            are public and that a record of the contribution (including all
            personal information I submit with it, including my sign-off) is
            maintained indefinitely and may be redistributed consistent with
            this project or the open source license(s) involved.

Note that not all upstream patches want to see Signed-off-by: lines. If
there is a clear indication that this line isn't wanted by a project's
upstream, we should avoid it as well.


Acks
----

If you agree with a patch, you might add your "Acked-by: <addr>" line.
The rules are like in the Linux kernel.


Usage in Cross Distributions
----------------------------

We use an additional tag that declares that the downstream build systems
of send-patches.org have agreed on this patch:

Used-in: <buildsystem>

where <buildsystem> can be one of the following (in alphabetical order):

	Buildroot (http://www.buildroot.net)
	crosstool-NG (http://crosstool-ng.org)
	OE-lite (http://oe-lite.org)
	OpenBricks (http://www.openbricks.org)
	PTXdist (http://www.ptxdist.org)

The Used-in: tag must only be given by one of the maintainers of the
buildsystems in question. Anyone who has write access to the
send-patches.org repository is allowed to give this tag for the
respective build system.

With the Used-in: tag, we would like to give a clear statement that this
patch is not only a random idea by any Joe Hacker from the other end of
the galaxy, but the joined oppinion of the major cross build systems out
there.


Send-patches.org Reference
--------------------------

When patches go upstream, they often end up in bug trackers and public
mailing list archives. In order to give a reference back to where this
patch comes from, the following tag may be used:

Send-patches-org: <url>

with <url> pointing to the gitweb location of the latest version of this
patch.


Patch Names
-----------

As the different build systems use different rules to sort the order of
the patches, we have agreed on using 4-digit numbered patch names (this
is for example what you get from 'git format-patch', but it is no
requirement to use this tool). Patch names end with ".patch". Example:

0001-fix-makefile.patch
0002-do-something-really-important.patch

Build systems might or might not have additional "series.<buildsystem>"
files to state which exact subset they use. These series files contain
one patch name per line, comment lines with a # as the first character
and no empty lines [2].


Upstream Status
---------------

The upstream status of a patch is documented with these tags:

Upstream-status: <pending, accepted, rejected>
Upstream-origin: <URL>
Upstream-comment: <comment>
Not-for-upstream: <comment>

The Not-for-upstream: tag shall only be given if either upstream is dead
or the problem is really a local hack where no proper fix is available.
Please try really, really hard to avoid this tag.


Directory Structure and Workflow
--------------------------------

The directory structure uses the name of the package plus it's version
number on the top level. The naming scheme follows the tarball
extraction naming scheme, for example:

	patches/libusb/1.0.8/

If the upstream tarball extracts only to a directory named after the
package name, the version shall be added on the next subdir level.

Below the package directory, each involved build system may have it's
own subdirectory, for example:

	patches/libusb/1.0.8/ptxdist/

If the build system finds a subdirectory with it's name, it shall use
the patches found there. If such a subdirectory does not exist, the
package directory shall be used to look for patches.

These rules allow the following workflow:

- A build system creates a package directory with the name and version
  of a package it has patches for.
- The build system adds it's patches to a <buildsystem>/ directory and
  adds it's Used-in: tags.
- The patches can be discussed on the mailing lists and it is possible
  to collect further Acked-by: tags.
- If the patch series has evolved up to a point where more build systems
  agree on the patches, the whole series can be moved upwards, to the
  package directory.
- Packages who are not participating in a series can just avoid their
  Used-in: tags and use their <buildsystem>/ subdirectory.


autogen.sh Scripts
------------------

A package directory may contain a script called autogen.sh. If this
script is there, it is being run by the build system after the patch
series has been applied and before the "configure" stage runs. This
mechanism can for example be used to run the autotools.

FIXME: Yann + Esben are strongly opposed against autogen scripts.


Open Issues
-----------

- Strategy for stable vs. development
- It might be possible to autogenerate the Send-patches-org: URL by
  using commit-hooks.
- The package directory naming scheme probably needs to be formalized
  more deeply

[1] http://lxr.linux.no/#linux+v3.1/Documentation/SubmittingPatches#L472
[2] there are broken quilt versions which cannot cope with empty lines