doc: Correct deftypefun for gpgme_op_decrypt_verify_start.
[gpgme.git] / 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.  If you want to add text
27   which shall not be copied to the ChangeLog, separate it by a line
28   consisting of two dashes at the begin of a line.
29
30   Note that ./autogen.sh installs a git hook to do some basic syntax
31   checking on the commit log message.
32
33   Typo fixes and documentation updates don't need a ChangeLog entry;
34   thus you would use a commit message like
35
36   #+begin_example
37   Fix typo in a comment
38
39   --
40   #+end_example
41
42   The marker line here is important; without it the first line would
43   appear in the ChangeLog.
44
45   If you exceptionally need to have longer lines in a commit log you may
46   do this after this scissor line:
47   #+begin_example
48   # ------------------------ >8 ------------------------
49   #+end_example
50   (hash, blank, 24 dashes, blank, scissor, blank, 24 dashes).
51   Note that such a comment will be removed if the git commit option
52   =--cleanup-scissor= is used.
53
54 ** License policy
55
56   GPGME is currently licensed under the LGPLv2.1+ with tools and the
57   manual being under the GPLv3+.  We may eventually update to a newer
58   version of the licenses or a combination of them.  It is thus
59   important, that all contributed code allows for an update of the
60   license; for example we can't accept code under the LGPLv2(only).
61
62   If you want to contribute code or documentation to GPGME you are
63   asked to assert that the contribution is in accordance to the "GPGME
64   Developer's Certificate of Origin" as found in the file "DCO".
65   Except for a slight wording change, this DCO is identical to the one
66   used by the Linux kernel.  Please take these simple steps:
67
68   - Decide which mail address you want to use.  Please have your real
69     name in the address and not a pseudonym.  Anonymous contributions
70     can only be done if you find a proxy who certifies for you.
71
72   - If your employer or school might claim ownership of code written
73     by you; you need to talk to them to make sure that you have the
74     right to contribute under the DCO.
75
76   - Send an OpenPGP signed mail to the gnupg-devel@gnupg.org public
77     mailing list from your mail address.  Include a copy of the DCO as
78     found in the official master branch.  Insert your name and email
79     address into the DCO in the same way you want to use it later.
80     Example:
81
82       Signed-off-by: Joe R. Hacker <joe@example.org>
83
84     If you need it, you may perform simple transformations on the mail
85     address: Replacing "@" by " at " or "." by " dot ".)
86
87   - That's it.  From now on you only need to add a "Signed-off-by:"
88     line with your name and mail address to the GIT commit message.
89     It is recommended to send the patches using a PGP/MIME signed
90     mail.
91
92 ** Coding standards
93
94   Please follow the GNU coding standards.  If you are in doubt consult
95   the existing code as an example.  Do no re-indent code without a
96   need.  If you really need to do it, use a separate commit for such a
97   change.
98
99   - C99 syntax should not be used; stick to C90.
100   - Please do not use C++ =//= style comments.
101   - Try to fit lines into 80 columns.
102   - Ignore signed/unsigned pointer mismatches
103   - No arithmetic on void pointers; cast to char* first.
104
105 ** Commit log keywords
106
107   - GnuPG-bug-id :: Values are comma or space delimited bug numbers
108                     from bug.gnupg.org pertaining to this commit.
109   - Debian-bug-id :: Same as above but from the Debian bug tracker.
110   - CVE-id :: CVE id number pertaining to this commit.
111   - Regression-due-to :: Commit id of the regression fixed by this commit.
112   - Fixes-commit :: Commit id this commit fixes.
113   - Reported-by :: Value is a name or mail address of a bug reporte.
114   - Suggested-by :: Value is a name or mail address of someone how
115                     suggested this change.
116   - Co-authored-by :: Name or mail address of a co-author
117   - Some-comments-by :: Name or mail address of the author of
118                         additional comments (commit log or code).
119   - Proofread-by :: Sometimes used by translation commits.
120   - Signed-off-by :: Name or mail address of the developer
121
122 * Debug hints
123
124   - Use gpgme-tool for manual tests.
125   - The envvar GPGME_DEBUG enables debugging; see debug.[ch] for
126     details.