Minor fixes to SHA assembly implementations
[libgcrypt.git] / doc / HACKING
index 51380b1..0cb8d56 100644 (file)
@@ -1,9 +1,86 @@
-                        Various hacking notes                  -*- text -*-
-                       =======================
+# HACKING                                                       -*- org -*-
+#+TITLE: Hacking notes for Libgcrypt
+#+STARTUP: showall
 
+* How to contribute
 
-Taking optimized MPI code out of GMP:
--------------------------------------
+  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 Libgcrypt.  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
+
+** 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.
+
+** License policy
+
+  Libgcrypt is currently licensed under the LGPLv2+ with tools and the
+  manual being under the GPLv2+.  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; for example we can't accept code under the LGPLv2(only).
+
+  Libgcrypt 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
+  "Libgcrypt 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 Libgcrypt 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 gcrypt-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.
+
+** 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.
+
+
+* Porting hints
+** Taking optimized MPI code out of GMP:
 
   I generated the pentium4/* files by glueing the existing assembler
   prologues to the GMP 4.2.1 assembler files generated with the m4
@@ -18,8 +95,9 @@ Taking optimized MPI code out of GMP:
   tedious work.
 
 
-Debugging math stuff:
----------------------
+* Debug hints
+
+** Debugging math stuff:
 
   While debugging the ECC code in libgcrypt, I was in need for some
   computer algebra system which would allow me to verify the numbers
@@ -29,38 +107,37 @@ Debugging math stuff:
 
   ===8<========
   hextodec(s)=local(v=Vec(s),a=10,b=11,c=12,d=13,e=14,f=15,A=10,B=11,C=12,D=13,E=14,F=15,h);if(#setunion(Set(v),Vec("0123456789ABCDEFabcdef"))>22,error);for(i=1,#v,h=shift(h,4)+eval(v[i]));h
-  
+
   p = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF")
   a = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC")
   b = hextodec("51953EB9618E1C9A1F929A21A0B68540EEA2DA725B99B315F3B8B489918EF109E156193951EC7E937B1652C0BD3BB1BF073573DF883D2C34F1EF451FD46B503F00")
-  
+
   /* Set up y^2 = x^3 + ax + b mod (p).  */
   e = ellinit(Mod(1,p)*[0,0,0,a,b]);
-  
+
   gx = hextodec ("00C6858E06B70404E9CD9E3ECB662395B4429C648139053FB521F828AF606B4D3DBAA14B5E77EFE75928FE1DC127A2FFA8DE3348B3C1856A429BF97E7E31C2E5BD66")
   gy = hextodec ("011839296A789A3BC0045C8A5FB42C7D1BD998F54449579B446817AFBD17273E662C97EE72995EF42640C550B9013FAD0761353C7086A272C24088BE94769FD16650")
   g = Mod(1,p)*[gx,gy]
-  
+
   n = hextodec ("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409")
-  
+
   /* Verify that G is on the curve, and that n is the order.  */
   ellisoncurve (e,g)
   isprime (n)
   ellpow (e,g,n)
-  
+
   d = hextodec ("018F9573F25059571BDF614529953DE2540497CEDABD04F3AF78813BED7BB163A2FD919EECF822848FCA39EF55E500F8CE861C7D53D371857F7774B79428E887F81B")
-  
+
   qx = hextodec ("00316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B3B")
   /* Note: WRONG! (It is apparent that this is the same as X shifted by
      8 bit).  */
   qy = hextodec ("0000316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B")
   q = Mod(1,p)*[qx,qy]
-  
+
   /* Calculate what Q should be given d.  */
   ellpow (e,g,d)
-  
+
   /* This is not 0 and thus shows that libgcrypt gave Q and d that do
   not match.  */
   ellpow (e,g,d) - q
   ====8<=====================
-