gpg: Remove the extra prompt for Curve25519.
[gnupg.git] / doc / HACKING
index f60f15d..2f3dd43 100644 (file)
@@ -32,11 +32,31 @@ TAB, will not exceed 80 columns.  If you want to add text which shall
 not be copied to the ChangeLog, separate it by a line consisting of
 two dashes at the begin of a line.
 
-Typo fixes and documentation updates don't need a ChangeLog Entry,
+The one-line summary usually starts with a keyword to identify the
+mainly affected subsystem.  If more than one keyword is required the
+are delimited by a comma (e.g. =scd,w32:=). Commonly found keywords
+are
+
+ - agent   :: The gpg-agent component
+ - ssh     :: The ssh-agent part of the agent
+ - common  :: Code in common
+ - iobuf   :: The IOBUF system in common
+ - gpg     :: The gpg or gpgv components
+ - gpgsm   :: The gpgsm component
+ - scd     :: The scdaemon component
+ - ccid    :: The CCID driver in scdaemon
+ - dirmngr :: The dirmngr component
+ - w32     :: Windows related code
+ - po      :: Translations
+ - build   :: Changes to the build system
+ - speedo  :: Speedo build system specific changes
+ - doc     :: Documentation changes
+
+Typo fixes and documentation updates don't need a ChangeLog entry;
 thus you would use a commit message like
 
 #+begin_example
-Fix type in a comment
+Fix typo in a comment
 
 --
 #+end_example
@@ -44,6 +64,16 @@ Fix type in a comment
 The marker line here is important; without it the first line would
 appear in the ChangeLog.
 
+If you exceptionally need to have longer lines in a commit log you may
+do this after this scissor line:
+#+begin_example
+# ------------------------ >8 ------------------------
+#+end_example
+(hash, blank, 24 dashes, blank, scissor, blank, 24 dashes).
+Note that such a comment will be removed if the git commit option
+=--cleanup=scissor= is used.
+
+
 ** License policy
 
   GnuPG is licensed under the GPLv3+ with some files under a mixed
@@ -60,8 +90,8 @@ appear in the ChangeLog.
   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 GnuPG and you
-  didn't signed a copyright assignment with the FSF in the past, you
+  If you want to contribute code or documentation to GnuPG and you
+  didn't sign 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
@@ -93,6 +123,52 @@ appear in the ChangeLog.
   need.  If you really need to do it, use a separate commit for such a
   change.
 
+  - Only certain C99 features may be used (see below); in general
+    stick to C90.
+  - Please do not use C++ =//= style comments.
+  - Try to fit lines into 80 columns.
+  - Ignore signed/unsigned pointer mismatches
+  - No arithmetic on void pointers; cast to char* first.
+  - We use our own printf style functions like =es_printf=, and
+    =es_asprintf= which implement most C99 features with the exception
+    of =wchar_t= (which should anyway not be used).  Please always use
+    them and do not resort to those provided by libc.  The rationale
+    for using them is that we know that the format specifiers work on
+    all platforms and that we do not need to chase platform dependent
+    bugs.
+  - It is common to have a label named "leave" for a function's
+    cleanup and return code.  This helps with freeing memory and is a
+    convenient location to set a breakpoint for debugging.
+  - Always use xfree() instead of free().  If it is not easy to see
+    that the freed variable is not anymore used, explicitly set the
+    variable to NULL.
+  - Init function local variables only if needed so that the compiler
+    can do a better job in detecting uninitialized variables which may
+    indicate a problem with the code.
+  - Never init static or file local variables to 0 to make sure they
+    end up in BSS.
+  - Use --enable-maintainer-mode with configure.
+
+*** C99 language features
+
+  In GnuPG 2.x, but *not in 1.4* and not in most libraries, a limited
+  set of C99 features may be used:
+
+  - Variadic macros:
+    : #define foo(a,...)  bar(a, __VA_ARGS__)
+
+  - The predefined macro =__func__=:
+    : log_debug ("%s: Problem with foo\n", __func__);
+
+  - Variable declaration inside a for():
+    : for (int i = 0; i < 5; ++)
+    :   bar (i);
+
+  Although we usually make use of the =u16=, =u32=, and =u64= types,
+  it is also possible to include =<stdint.h>= and use =int16_t=,
+  =int32_t=, =int64_t=, =uint16_t=, =uint32_t=, and =uint64_t=.  But do
+  not use =int8_t= or =uint8_t=.
+
 ** Commit log keywords
 
   - GnuPG-bug-id :: Values are comma or space delimited bug numbers
@@ -145,7 +221,6 @@ appear in the ChangeLog.
    the git repositories.  In case of problems, don't hesitate to ask
    on the gnupg-devel mailing for help.
 
-
 * Debug hints
 
   See the manual for some hints.