HACKING

   1      Rules for commits on the xmlsec module
   2      =========================================
   3
   4 0) DO NOT COMMIT DIRECTLY !
   5 If you have a patch send a mail to xmlsec@aleksey.com mailing
   6 list (you must be subscribed to the list, go to
   7 http://www.aleksey.com/mailman/listinfo/xmlsec to subscribe).
   8
   9 If there is a problem in xmlsec module that prevents you
  10 from building other major components then feel free to patch
  11 first and then send a mail. This is an EXCEPTIONAL case and
  12 you should be VERY carefull when you are doing this.
  13
  14 Igor Zlatkovic get an exception for the send before commit rule.
  15
  16 1) Coding style.
  17     - Formatting. Just for clarification, the formating is:
  18
  19         tab size=8;indentation=4;insert spaces=yes
  20
  21     - Use explicit "!= NULL", "!= 0", etc. This makes code
  22     easier to read and remove warnings on some platform.
  23     Example:
  24         BAD:
  25             if(a)
  26         GOOD:
  27             if(a != NULL)
  28         or
  29             if(a != 0)
  30
  31    - Put figure brackets '{}' even if you have only one operator
  32    in "if", "for", etc. This also makes code easier to read and
  33    saves a lot of time when you need to quickly change something.
  34    Example:
  35         BAD:
  36              if(a != NULL)
  37                 xmlFree(a);
  38         GOOD:
  39              if(a != NULL) {
  40                 xmlFree(a);
  41             }
  42
  43     - Use round brackets '()' in conditions to show the precedence order.
  44     I don't remember what goes first '<<' or '*', do you?
  45     Example:
  46         BAD:
  47             if(privkey == NULL || pubkey == NULL)
  48         GOOD:
  49             if((privkey == NULL) || (pubkey == NULL))
  50
  51    - Use round brackets '()' for "return".
  52    Example:
  53         BAD:
  54             return 0;
  55         GOOD:
  56             return(0);
  57
  58     - Check for warnings! Use "--enable-pedantic" option
  59     for "configure.in" script to enable as much warnings as possible.
  60     Your patch should produce no new warnings and if you'll
  61     see something that you can fix, then do it.
  62
  63     - Check for memory leaks. There is a built in support for
  64     valgrind (http://devel-home.kde.org/~sewardj/). In order to use it,
  65     use "enable_static_linking" option for "configure.in" script to
  66     force static linking of xmlsec command line utility and run
  67     "make memcheck" from the top xmlsec source folder. The results are printed
  68     at the end. More detailed logs could be found in /tmp/test*.log files.
  69
  70 2) Coding practice
  71     - You should trust nobody! Anyone can fool you: user or another application
  72     might provide you incorrect data; call to xmlsec or system function might
  73     fail with an error code; worse, the same call might fail but the return
  74     code is "success" and so on. The patch fixes a lot of places where the
  75     original code failed to check input data or function return values.
  76     One of my favorite examples is the code that *silently* assumed that
  77     base64 decoded value of a RSA public exponent obtained from XML fits
  78     in a DWORD. And after that the code did memcpy to copy from xmlSecBuffer
  79     to a DWORD variable *without* checking how much data are actualy copied!
  80     The trivial DoS attack (at least DoS!!!) is to put very long base64 string
  81     in XML file and enjoy the server crash.
  82     One of the strongest sides of xmlsec library is that there are very few
  83     known ways to crash it (and all of them are related to running the
  84     application in an environment with a very limited memory to force a malloc
  85     failure). To be a little paranoid is good in this context :)
  86
  87     - malloc/free vs. xmlMalloc/xmlFree
  88     xmlsec library use libxml2 memory management functions. This provides an
  89     easy way to replace default memory management functions with custom ones.
  90     And this might be very usefull in some cases.
  91     Note that crypto library might use a different memory management
  92     functions! Be very carefully to do not mix them (i.e. get memory
  93     allocated by crypto library function and free it with xmFree).
  94
  95     - Errors reporting (XMLSEC_ERRORS_R_XMLSEC_FAILED vs. XMLSEC_ERRORS_R_CRYPTO_FAILED)
  96     The correct usage rule is:
  97         if the failed function starts with "xmlSec" then use
  98             XMLSEC_ERRORS_R_XMLSEC_FAILED
  99         else if it is xmlMalloc/xmlFree/xmlStrdup/etc then use
 100             XMLSEC_ERRORS_R_MALLOC_FAILED
 101         else if the function starts with "xml" or "xslt" (i.e. it comes
 102         from libxml or libxslt) then use
 103             XMLSEC_ERRORS_R_XML_FAILED
 104         else if it is related to IO (fopen, fread, fwrite, etc.) then use
 105             XMLSEC_ERRORS_R_IO_FAILED
 106         else if the function could be used only from xmlsec-crypto (i.e.
 107         it is crypto engine related) then use
 108             XMLSEC_ERRORS_R_CRYPTO_FAILED
 109         else if there is another reason (invalid data, invalid size, etc.)
 110             corresponding error reason should be used
 111         else
 112             it is something new and should be discussed
 113         fi
 114     Correct error reason is very important. For example,  some applications
 115     ignore all the XMLSEC_ERRORS_R_XMLSEC_FAILED errors to get to the bottom of
 116     the errors stack and report the actual problem.
 117
 118     - Errors reporting: "size=%d;error=%d" instead of "size %d, error: %d":
 119     It would be great if xmlsec-crypto libraries can follow the error message
 120     standard adopted in the other files of xmlsec library:
 121         "<name1>=<value1>;<name2>=<value2>;..."
 122     This greatly helps when one needs to write a logs parser. For example, to
 123     find the reason of memory allocation failures.
 124
 125 3) Preparing and submitting a patch.
 126 If you want to submit a patch please create a pull request on GitHub and then
 127    send your pull request along with a short description of the problem or feature
 128     you are fixing/implementing to the xmlsec@aleksey.com mailing list
 129     (you must be subscribed to the list, go to http://www.aleksey.com/mailman/listinfo/xmlsec to subscribe).
 130     If you are fixing a bug, it might be a good idea to create a GitHub ticket first
 131     (http://www.aleksey.com/xmlsec/bugs.html) for the record.
 132
 133 4) Building a release
 134 - Cleanup, make sure no other changes are pending
 135   - make distclean
 136   - git status
 137 - Update Changelog
 138 - Write about release changes in the release
 139   - docs/index.html and docs/news.html
 140 - Update release number in
 141   - configure.in (2 places at the top)
 142   - docs/download.html
 143 - Create build
 144   - ./autogen.sh
 145   - make
 146 - Build docs (watch for errors!)
 147   - make docs
 148 - Commit the "prepare for X.Y.Z" release
 149   - git commit -m"prepare for X.Y.Z release" -a
 150 - Run tests, make sure everything is OK
 151   - make check
 152 - Build release
 153   - sudo ./scripts/build_release.sh
 154 - Extract tar file, make sure it works
 155   - cd /tmp
 156   - tar xvfz /usr/src/redhat/SOURCE/xmlsec1-X.Y.z.tar.gz
 157   - cd xmlsec1-X.Y.z
 158   - ./configure
 159   - make
 160   - make check
 161 - Copy tar file to FTP/Web Download
 162 - Copy docs/ folder to Web folder
 163 - Write an announcement email to xmlsec@aleksey.com
 164 - Update freshmeat.net
 165 - Relax
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176