docs/patch-policy.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[patch-policy]]
   5
   6 Patching a package
   7 ------------------
   8
   9 While integrating a new package or updating an existing one, it may be
  10 necessary to patch the source of the software to get it cross-built within
  11 OpenADK.  OpenADK offers an infrastructure to automatically handle this during
  12 the builds.  Patches are provided within OpenADK, in the package directory;
  13 these typically aim to fix cross-compilation, libc support, portability issues
  14 or other things.
  15
  16 Normally the patches are autogenerated via:
  17 ------------
  18  $ make package=<package> update-patches
  19 ------------
  20
  21 Otherwise they are manually generated via:
  22 ------------
  23  $ diff -Nur <pkgname>-<pkgversion>.orig <pkgname>-<pkgversion> > package/<pkgname>/patches/xxx-description.patch
  24 ------------
  25
  26 The string +xxx+ should be substituted by a number starting with 001. The
  27 patches will be applied in numeric order.  You should either use the automatic
  28 patch generation or the manual patch creation for a package. Mixed usage is not
  29 supported.
  30
  31 Format and licensing of the package patches
  32 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  33
  34 Patches are released under the same license as the software that is
  35 modified.
  36
  37 A message explaining what the patch does, and why it is needed, should
  38 be added in the header commentary of the patch.
  39 At the end, the patch should look like:
  40
  41 ---------------
  42 add C++ support test
  43
  44 --- configure.ac.orig
  45 +++ configure.ac
  46 @@ -40,2 +40,12 @@
  47
  48 AC_PROG_MAKE_SET
  49 +
  50 +AC_CACHE_CHECK([whether the C++ compiler works],
  51 +               [rw_cv_prog_cxx_works],
  52 +               [AC_LANG_PUSH([C++])
  53 +                AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
  54 +                               [rw_cv_prog_cxx_works=yes],
  55 +                               [rw_cv_prog_cxx_works=no])
  56 +                AC_LANG_POP([C++])])
  57 +
  58 +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
  59 ---------------
  60
  61 Integrating patches found on the Web
  62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  63
  64 When integrating a patch of which you are not the author, you have to
  65 add a few things in the header of the patch itself.
  66
  67 Depending on whether the patch has been obtained from the project
  68 repository itself, or from somewhere on the web, add one of the
  69 following tags:
  70
  71 ---------------
  72 Backported from: <some commit id>
  73 ---------------
  74
  75 or
  76
  77 ---------------
  78 Fetch from: <some url>
  79 ---------------
  80
  81 It is also sensible to add a few words about any changes to the patch
  82 that may have been necessary.
  83
  84 Upstreaming patches
  85 ~~~~~~~~~~~~~~~~~~~
  86
  87 OpenADK tries to avoid any patches to the source code. If a patch could
  88 not be avoided, it should be tried to make the patch of a good quality to
  89 get it upstream. OpenADK tries to report any found issues and try to send
  90 in any upstream compatible patches.