home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / boot / i386 / rescue / usr / share / doc / packages / dbus-1 / HACKING < prev    next >
Encoding:
Text File  |  2006-11-29  |  8.3 KB  |  235 lines
  1. The guidelines in this file are the ideals; it's better to send a
  2. not-fully-following-guidelines patch than no patch at all, though.  We
  3. can always polish it up.
  4.  
  5. Mailing list
  6. ===
  7.  
  8. The D-Bus mailing list is message-bus-list@freedesktop.org; discussion
  9. of patches, etc. should go there.
  10.  
  11. Security
  12. ===
  13.  
  14. Most of D-Bus is security sensitive.  Guidelines related to that:
  15.  
  16.  - avoid memcpy(), sprintf(), strlen(), snprintf, strlcat(),
  17.    strstr(), strtok(), or any of this stuff. Use DBusString. 
  18.    If DBusString doesn't have the feature you need, add it 
  19.    to DBusString. 
  20.  
  21.    There are some exceptions, for example
  22.    if your strings are just used to index a hash table 
  23.    and you don't do any parsing/modification of them, perhaps
  24.    DBusString is wasteful and wouldn't help much. But definitely 
  25.    if you're doing any parsing, reallocation, etc. use DBusString.
  26.  
  27.  - do not include system headers outside of dbus-memory.c, 
  28.    dbus-sysdeps.c, and other places where they are already 
  29.    included. This gives us one place to audit all external 
  30.    dependencies on features in libc, etc.
  31.  
  32.  - do not use libc features that are "complicated" 
  33.    and may contain security holes. For example, you probably shouldn't
  34.    try to use regcomp() to compile an untrusted regular expression.
  35.    Regular expressions are just too complicated, and there are many 
  36.    different libc's out there.
  37.  
  38.  - we need to design the message bus daemon (and any similar features)
  39.    to use limited privileges, run in a chroot jail, and so on.
  40.  
  41. http://vsftpd.beasts.org/ has other good security suggestions.
  42.  
  43. Coding Style
  44. ===
  45.  
  46.  - The C library uses GNU coding conventions, with GLib-like
  47.    extensions (e.g. lining up function arguments). The
  48.    Qt wrapper uses KDE coding conventions.
  49.  
  50.  - Write docs for all non-static functions and structs and so on. try
  51.    "doxygen Doxyfile" prior to commit and be sure there are no
  52.    warnings printed.
  53.  
  54.  - All external interfaces (network protocols, file formats, etc.)
  55.    should have documented specifications sufficient to allow an
  56.    alternative implementation to be written. Our implementation should
  57.    be strict about specification compliance (should not for example
  58.    heuristically parse a file and accept not-well-formed
  59.    data). Avoiding heuristics is also important for security reasons;
  60.    if it looks funny, ignore it (or exit, or disconnect).
  61.  
  62. Making a release
  63. ===
  64.  
  65. To make a release of D-Bus, do the following:
  66.  
  67.  - check out a fresh copy from CVS
  68.  
  69.  - verify that the libtool versioning/library soname is 
  70.    changed if it needs to be, or not changed if not
  71.  
  72.  - update the file NEWS based on the ChangeLog
  73.  
  74.  - update the AUTHORS file based on the ChangeLog
  75.  
  76.  - add a ChangeLog entry containing the version number 
  77.    you're releasing ("Released 0.3" or something)
  78.    so people can see which changes were before and after
  79.    a given release.
  80.  
  81.  - The version number should have major.minor.micro even
  82.    if micro is 0, i.e. "1.0.0" and "1.2.0" not "1.0"/"1.2"
  83.  
  84.  - "make distcheck" (DO NOT just "make dist" - pass the check!)
  85.  
  86.  - if make distcheck fails, fix it.
  87.  
  88.  - once distcheck succeeds, "cvs commit"
  89.  
  90.  - if someone else made changes and the commit fails, 
  91.    you have to "cvs up" and run "make distcheck" again
  92.  
  93.  - once the commit succeeds, "cvs tag DBUS_X_Y_Z" where 
  94.    X_Y_Z map to version X.Y.Z
  95.  
  96.  - bump the version number up in configure.in, and commit
  97.    it.  Make sure you do this *after* tagging the previous
  98.    release! The idea is that CVS has a newer version number
  99.    than anything released.
  100.  
  101.  - scp your tarball to freedesktop.org server and copy it 
  102.    to /srv/dbus.freedesktop.org/www/releases. This should 
  103.    be possible if you're in group "dbus"
  104.  
  105.  - update the wiki page http://www.freedesktop.org/Software/dbus by
  106.    adding the new release under the Download heading. Then, cut the
  107.    link and changelog for the previous that was there.
  108.  
  109.  - update the wiki page
  110.    http://www.freedesktop.org/Software/DbusReleaseArchive pasting the
  111.    previous release. Note that bullet points for each of the changelog
  112.    items must be indented three more spaces to conform to the
  113.    formatting of the other releases there.
  114.   
  115.  - post to dbus@lists.freedesktop.org announcing the release.
  116.  
  117.  
  118. After making a ".0" stable release
  119. ===
  120.  
  121. After releasing, when you increment the version number in CVS, also
  122. move the ChangeLog to ChangeLog.pre-X-Y where X-Y is what you just
  123. released, e.g. ChangeLog.pre-1-0. Then create and cvs add a new empty
  124. ChangeLog. The last entry in ChangeLog.pre-1-0 should be the one about
  125. "Released 1.0". 
  126.  
  127. Add ChangeLog.pre-X-Y to EXTRA_DIST in Makefile.am.
  128.  
  129. We create a branch for each stable release; sometimes the branch is
  130. not done immediately, instead it's possible to wait until someone has
  131. a not-suitable-for-stable change they want to make and then branch to
  132. allow committing that change.
  133.  
  134. The branch name should be DBUS_X_Y_BRANCH which is a branch that has
  135. releases versioned X.Y.Z
  136.  
  137. To branch, tag HEAD with DBUS_X_Y_BRANCHPOINT:
  138.  cvs tag DBUS_X_Y_BRANCHPOINT
  139. then create the branch from that tag:
  140.  cvs rtag -b -r DBUS_X_Y_BRANCHPOINT DBUS_X_Y_BRANCH dbus
  141.  
  142. Note that DBUS_X_Y_BRANCHPOINT may not tag the same revision as the
  143. DBUS_X_Y_0 release, since we may not branch immediately.
  144.  
  145. Environment variables
  146. ===
  147.  
  148. These are the environment variables that are used by the D-Bus client library
  149.  
  150. DBUS_VERBOSE=1
  151. Turns on printing verbose messages. This only works if D-Bus has been
  152. compiled with --enable-verbose-mode
  153.  
  154. DBUS_MALLOC_FAIL_NTH=n
  155. Can be set to a number, causing every nth call to dbus_alloc or
  156. dbus_realloc to fail. This only works if D-Bus has been compiled with
  157. --enable-tests.
  158.  
  159. DBUS_MALLOC_FAIL_GREATER_THAN=n
  160. Can be set to a number, causing every call to dbus_alloc or
  161. dbus_realloc to fail if the number of bytes to be allocated is greater
  162. than the specified number. This only works if D-Bus has been compiled with
  163. --enable-tests.
  164.  
  165. DBUS_TEST_MALLOC_FAILURES=n
  166. Many of the D-Bus tests will run over and over, once for each malloc
  167. involved in the test. Each run will fail a different malloc, plus some
  168. number of mallocs following that malloc (because a fair number of bugs
  169. only happen if two or more mallocs fail in a row, e.g. error recovery
  170. that itself involves malloc).  This env variable sets the number of
  171. mallocs to fail.
  172. Here's why you care: If set to 0, then the malloc checking is skipped,
  173. which makes the test suite a heck of a lot faster. Just run with this
  174. env variable unset before you commit.
  175.  
  176. Tests
  177. ===
  178.  
  179. These are the test programs that are built if dbus is compiled using
  180. --enable-tests.
  181.  
  182. dbus/dbus-test
  183. This is the main unit test program that tests all aspects of the D-Bus
  184. client library.
  185.  
  186. dbus/bus-test
  187. This it the unit test program for the message bus.
  188.  
  189. test/break-loader
  190. A test that tries to break the message loader by passing it randomly
  191. created invalid messages.
  192.  
  193. "make check" runs all the deterministic test programs (i.e. not break-loader).
  194.  
  195. "make check-coverage" is available if you configure with --enable-gcov and 
  196. gives a complete report on test suite coverage. You can also run 
  197. "test/decode-gcov foo.c" on any source file to get annotated source, 
  198. after running make check with a gcov-enabled tree.
  199.  
  200. Patches
  201. ===
  202.  
  203. Please file them at http://bugzilla.freedesktop.org under component
  204. dbus, and also post to the mailing list for discussion.  The commit
  205. rules are:
  206.  
  207.  - for fixes that don't affect API or protocol, they can be committed
  208.    if any one qualified reviewer other than patch author
  209.    reviews and approves
  210.  
  211.  - for fixes that do affect API or protocol, two people
  212.    in the reviewer group have to review and approve the commit, and 
  213.    posting to the list is definitely mandatory
  214.  
  215.  - if there's a live unresolved controversy about a change,
  216.    don't commit it while the argument is still raging.
  217.  
  218.  - regardless of reviews, to commit a patch:
  219.     - make check must pass
  220.     - the test suite must be extended to cover the new code
  221.       as much as reasonably feasible
  222.     - the patch has to follow the portability, security, and 
  223.       style guidelines
  224.     - the patch should as much as reasonable do one thing, 
  225.       not many unrelated changes
  226.    No reviewer should approve a patch without these attributes, and
  227.    failure on these points is grounds for reverting the patch.
  228.  
  229. The reviewer group that can approve patches: Havoc Pennington, Michael
  230. Meeks, Alex Larsson, Zack Rusin, Joe Shaw, Mikael Hallendal, Richard
  231. Hult, Owen Fraser-Green, Olivier Andrieu, Colin Walters, Thiago
  232. Macieira, John Palmieri.
  233.  
  234.  
  235.