# HACKING                                                       -*- org -*-
#+TITLE: Hacking notes for Libassuan
#+STARTUP: showall

* How to contribute

  The following stuff explains some basic procedures you need to
  follow if you want to contribute code or documentation.

** No more ChangeLog files

  Do not modify any of the ChangeLog files in Libassuan.  Starting
  on December 1st, 2011 we put change information only in the GIT
  commit log, and generate a top-level ChangeLog file from logs at
  "make dist" time.  As such, there are strict requirements on the
  form of the commit log messages.  The old ChangeLog files have all
  be renamed to ChangeLog-2011


** Coding standards

  Please follow the GNU coding standards.  If you are in doubt consult
  the existing code as an example.  Do no re-indent code without a
  need.  If you really need to do it, use a separate commit for such a
  change.  See below for the required commit log format.

** Commit log requirements

  Your commit log should always start with a one-line summary, the
  second line should be blank, and the remaining lines are usually
  ChangeLog-style entries for all affected files.  However, it's fine
  -- even recommended -- to write a few lines of prose describing the
  change, when the summary and ChangeLog entries don't give enough of
  the big picture.  Omit the leading TABs that you're used to seeing
  in a "real" ChangeLog file, but keep the maximum line length at 72
  or smaller, so that the generated ChangeLog lines, each with its
  leading TAB, will not exceed 80 columns.

  Here is an example of a commit message:
#+begin_example
Make new functions also visible on non-W32.

* src/system-posix.c (__assuan_read, __assuan_write, __assuan_recvmsg)
(__assuan_sendmsg, __assuan_waitpid): Make functions global.
* src/libassuan.vers: Add above functions.
* configure.ac: Set version to 2.1.0-git.
--
Note that everything after the above tear off marker will not be
copied to the ChangeLog during a "make dist".  You may use this to add
extra information about this commit which are mostly relevant for your
co-hackers.  Recall that the ChangeLog itself fulfills requirements of
the GPL and is useful for quick history checks of a released version.
Developers will use the git log.
#+end_example

  If you don't want a ChangeLog entry at all, use this:
#+begin_example
Give examples for commit logs.

--
Because the tear off line is the first line of the body, not even the
summary line will be copied to the ChangeLog.  Using only the tear off
line without any text is often useful for commits like "Typo and
grammar fixes."
#+end_example


** License policy

  Libassuan is currently licensed under the LGPLv2+ with tools and the
  manual being under the GPLv3+.  We may eventually update to a newer
  version of the licenses or a combination of them.  It is thus
  important, that all contributed code allows for an update of the
  license; in particular we can't accept code under the GPL or LGPL
  without the "or any later version" term.

  Being developed as part of GnuPG-2, Libassuan used to have a strict
  policy of requiring copyright assignments to the FSF.  To avoid this
  major organizational overhead and to allow inclusion of code, not
  copyrighted by the FSF, this policy has been relaxed.  It is now
  also possible to contribute code by asserting that the contribution
  is in accordance to the "Libassuan Developer's Certificate of
  Origin" as found in the file "DCO".  (Except for a slight wording
  change, this DCO is identical to the one used by the Linux kernel.)

  If your want to contribute code or documentation to Libassuan and
  you didn't signed a copyright assignment with the FSF in the past,
  you need to take these simple steps:

  - Decide which mail address you want to use.  Please have your real
    name in the address and not a pseudonym.  Anonymous contributions
    can only be done if you find a proxy who certifies for you.

  - If your employer or school might claim ownership of code written
    by you; you need to talk to them to make sure that you have the
    right to contribute under the DCO.

  - Send an OpenPGP signed mail to the gnupg-devel@gnupg.org mailing
    list from your mail address.  Include a copy of the DCO as found
    in the official master branch.  Insert your name and email address
    into the DCO in the same way you want to use it later.  Example:

      Signed-off-by: Joe R. Hacker <joe@example.org>

    (If you really need it, you may perform simple transformations of
    the mail address: Replacing "@" by " at " or "." by " dot ".)

  - That's it.  From now on you only need to add a "Signed-off-by:"
    line with your name and mail address to the commit message.  It is
    recommended to send the patches using a PGP/MIME signed mail.