// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

[[patch-policy]]

Patching a package
------------------

While integrating a new package or updating an existing one, it may be
necessary to patch the source of the software to get it cross-built within
OpenADK.  OpenADK offers an infrastructure to automatically handle this during
the builds.  Patches are provided within OpenADK, in the package directory;
these typically aim to fix cross-compilation, libc support, portability issues
or other things.

Normally the patches are autogenerated via:
------------
 $ make package=<package> update-patches
------------

Otherwise they are manually generated via:
------------
 $ diff -Nur <pkgname>-<pkgversion>.orig <pkgname>-<pkgversion> > package/<pkgname>/patches/xxx-description.patch 
------------

The string +xxx+ should be substituted by a number starting with 001. The
patches will be applied in numeric order.  You should either use the automatic
patch generation or the manual patch creation for a package. Mixed usage is not
supported.

Format and licensing of the package patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Patches are released under the same license as the software that is
modified.

A message explaining what the patch does, and why it is needed, should
be added in the header commentary of the patch.
At the end, the patch should look like:

---------------
add C++ support test

--- configure.ac.orig
+++ configure.ac
@@ -40,2 +40,12 @@

AC_PROG_MAKE_SET
+
+AC_CACHE_CHECK([whether the C++ compiler works],
+               [rw_cv_prog_cxx_works],
+               [AC_LANG_PUSH([C++])
+                AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
+                               [rw_cv_prog_cxx_works=yes],
+                               [rw_cv_prog_cxx_works=no])
+                AC_LANG_POP([C++])])
+
+AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
---------------

Integrating patches found on the Web
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When integrating a patch of which you are not the author, you have to
add a few things in the header of the patch itself.

Depending on whether the patch has been obtained from the project
repository itself, or from somewhere on the web, add one of the
following tags:

---------------
Backported from: <some commit id>
---------------

or

---------------
Fetch from: <some url>
---------------

It is also sensible to add a few words about any changes to the patch
that may have been necessary.

Upstreaming patches
~~~~~~~~~~~~~~~~~~~

OpenADK tries to avoid any patches to the source code. If a patch could
not be avoided, it should be tried to make the patch of a good quality to
get it upstream. OpenADK tries to report any found issues and try to send
in any upstream compatible patches.