doc/HACKING

   1 # HACKING                                                       -*- org -*-
   2 #+TITLE: Hacking notes for GPGME
   3 #+STARTUP: showall
   4
   5 * How to contribute
   6 ** No more ChangeLog files
   7
   8   Do not modify any of the ChangeLog files in GPGME.  Starting
   9   on December 1st, 2011 we put change information only in the GIT
  10   commit log, and generate a top-level ChangeLog file from logs at
  11   "make dist" time.  As such, there are strict requirements on the
  12   form of the commit log messages.  The old ChangeLog files have all
  13   be renamed to ChangeLog-2011
  14
  15
  16 ** Commit log requirements
  17
  18   Your commit log should always start with a one-line summary, the
  19   second line should be blank, and the remaining lines are usually
  20   ChangeLog-style entries for all affected files.  However, it's fine
  21   -- even recommended -- to write a few lines of prose describing the
  22   change, when the summary and ChangeLog entries don't give enough of
  23   the big picture.  Omit the leading TABs that you're used to seeing
  24   in a "real" ChangeLog file, but keep the maximum line length at 72
  25   or smaller, so that the generated ChangeLog lines, each with its
  26   leading TAB, will not exceed 80 columns.
  27
  28   Note that ./autogen.sh installs a git hook to do some basic syntax
  29   checking on the commit log message.
  30
  31 ** License policy
  32
  33   GPGME is currently licensed under the LGPLv2.1+ with tools and the
  34   manual being under the GPLv3+.  We may eventually update to a newer
  35   version of the licenses or a combination of them.  It is thus
  36   important, that all contributed code allows for an update of the
  37   license; for example we can't accept code under the LGPLv2(only).
  38
  39   If you want to contribute code or documentation to GPGME you are
  40   asked to assert that the contribution is in accordance to the "GPGME
  41   Developer's Certificate of Origin" as found in the file "DCO".
  42   Except for a slight wording change, this DCO is identical to the one
  43   used by the Linux kernel.  Please take these simple steps:
  44
  45   - Decide which mail address you want to use.  Please have your real
  46     name in the address and not a pseudonym.  Anonymous contributions
  47     can only be done if you find a proxy who certifies for you.
  48
  49   - If your employer or school might claim ownership of code written
  50     by you; you need to talk to them to make sure that you have the
  51     right to contribute under the DCO.
  52
  53   - Send an OpenPGP signed mail to the gnupg-devel@gnupg.org public
  54     mailing list from your mail address.  Include a copy of the DCO as
  55     found in the official master branch.  Insert your name and email
  56     address into the DCO in the same way you want to use it later.
  57     Example:
  58
  59       Signed-off-by: Joe R. Hacker <joe@example.org>
  60
  61     If you need it, you may perform simple transformations on the mail
  62     address: Replacing "@" by " at " or "." by " dot ".)
  63
  64   - That's it.  From now on you only need to add a "Signed-off-by:"
  65     line with your name and mail address to the GIT commit message.
  66     It is recommended to send the patches using a PGP/MIME signed
  67     mail.
  68
  69 ** Coding standards
  70
  71   Please follow the GNU coding standards.  If you are in doubt consult
  72   the existing code as an example.  Do no re-indent code without a
  73   need.  If you really need to do it, use a separate commit for such a
  74   change.
  75
  76 * Debug hints
  77
  78   - Use gpgme-tool for manual tests.
  79   - The envvar GPGME_DEBUG enables debugging; see debug.[ch] for
  80     details.