gpg: Emit FAILURE stati now in almost all cases.
[gnupg.git] / doc / HACKING
index 1888b29..bd16856 100644 (file)
@@ -38,28 +38,31 @@ 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
+ - build   :: Changes to the build system
+ - ccid    :: The CCID driver in scdaemon
  - common  :: Code in common
- - iobuf   :: The IOBUF system in common
+ - dirmngr :: The dirmngr component
+ - doc     :: Documentation changes
  - gpg     :: The gpg or gpgv components
- - gpgsm   :: The gpgsm component
+ - sm      :: The gpgsm component (also "gpgsm")
+ - gpgscm  :: The regression test driver
+ - indent  :: Indentation and similar changes
+ - iobuf   :: The IOBUF system in common
+ - po      :: Translations
  - scd     :: The scdaemon component
- - ccid    :: The CCID driver in scdaemon
- - dirmngr :: The dirmngr component
- - wks     :: The web key service tools
+ - speedo  :: Speedo build system specific changes
+ - ssh     :: The ssh-agent part of the agent
+ - tests   :: The regressions tests
  - tools   :: Other code in tools
  - w32     :: Windows related code
- - po      :: Translations
- - build   :: Changes to the build system
- - speedo  :: Speedo build system specific changes
- - doc     :: Documentation changes
- - indent  :: Indentation and similar changes
+ - wks     :: The web key service tools
+ - yat2m   :: The yat2m tool.
 
 Typo fixes and documentation updates don't need a ChangeLog entry;
 thus you would use a commit message like
 
 #+begin_example
-Fix typo in a comment
+doc: Fix typo in a comment
 
 --
 #+end_example
@@ -128,9 +131,28 @@ Note that such a comment will be removed if the git commit option
   - Only certain C99 features may be used (see below); in general
     stick to C90.
   - Please do not use C++ =//= style comments.
+  - Do not use comments like:
+#+begin_src
+      if (foo)
+        /* Now that we know that foo is true we can call bar.  */
+        bar ();
+#+end_src
+    instead write the comment on the if line or before it.  You may
+    also use a block and put the comment inside.
+  - Please use asterisks on the left of longer comments.  This makes
+    it easier to read without syntax highlighting, on printouts, and
+    for blind people.
   - Try to fit lines into 80 columns.
   - Ignore signed/unsigned pointer mismatches
   - No arithmetic on void pointers; cast to char* first.
+  - Do not use
+#+begin_src
+      if ( 42 == foo )
+#+end_src
+    this is harder to read and modern compilers are pretty good in
+    detecing accidential assignments.  It is also suggested not to
+    compare to 0 or NULL but to test the value direct or with a '!';
+    this makes it easier to see that a boolean test is done.
   - We use our own printf style functions like =es_printf=, and
     =gpgrt_asprintf= (or the =es_asprintf= macro) which implement most
     C99 features with the exception of =wchar_t= (which should anyway
@@ -145,12 +167,17 @@ Note that such a comment will be removed if the git commit option
   - 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.
+  - New code shall in general use xtrymalloc or xtrycalloc and check
+    for an error (use gpg_error_from_syserror()).
   - 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.
+  - Put extra parenthesis around terms with binary operators to make
+    it clear that the binary operator was indeed intended.
+  - Use --enable-maintainer-mode with configure so that all suitable
+    warnings are enabled.
 
 ** Variable names
 
@@ -197,6 +224,7 @@ Note that such a comment will be removed if the git commit option
   - CVE-id :: CVE id number pertaining to this commit.
   - Regression-due-to :: Commit id of the regression fixed by this commit.
   - Fixes-commit :: Commit id this commit fixes.
+  - Updates-commit :: Commit id this commit updates.
   - Reported-by :: Value is a name or mail address of a bug reporte.
   - Suggested-by :: Value is a name or mail address of someone how
                     suggested this change.
@@ -321,7 +349,7 @@ Note that such a comment will be removed if the git commit option
   - g10/mdfilter.c :: Filter to calculate hashs
   - g10/textfilter.c :: Filter to handle CR/LF and trailing white space
   - g10/cipher.c   :: En-/Decryption filter
-  - g10/misc.c     :: Utlity functions
+  - g10/misc.c     :: Utility functions
   - g10/options.h  :: Structure with all the command line options
                       and related constants
   - g10/openfile.c :: Create/Open Files
@@ -331,7 +359,7 @@ Note that such a comment will be removed if the git commit option
 
   - g10/pubkey-enc.c :: Process a public key encoded packet.
   - g10/seckey-cert.c :: Not anymore used
-  - g10/seskey.c     :: Make sesssion keys etc.
+  - g10/seskey.c     :: Make session keys etc.
   - g10/import.c     :: Import keys into our key storage.
   - g10/export.c     :: Export keys to the OpenPGP format.
   - g10/sign.c       :: Create signature and optionally encrypt.