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: