Mailing list
===
-The D-BUS mailing list is message-bus-list@freedesktop.org; discussion
+The D-Bus mailing list is dbus@lists.freedesktop.org; discussion
of patches, etc. should go there.
Security
===
-Most of D-BUS is security sensitive. Guidelines related to that:
+Most of D-Bus is security sensitive. Guidelines related to that:
- avoid memcpy(), sprintf(), strlen(), snprintf, strlcat(),
strstr(), strtok(), or any of this stuff. Use DBusString.
data). Avoiding heuristics is also important for security reasons;
if it looks funny, ignore it (or exit, or disconnect).
+Making a release
+===
+
+To make a release of D-Bus, do the following:
+
+ - check out a fresh copy from CVS
+
+ - verify that the libtool versioning/library soname is
+ changed if it needs to be, or not changed if not
+
+ - update the file NEWS based on the ChangeLog
+
+ - update the AUTHORS file based on the ChangeLog
+
+ - add a ChangeLog entry containing the version number
+ you're releasing ("Released 0.3" or something)
+ so people can see which changes were before and after
+ a given release.
+
+ - The version number should have major.minor.micro even
+ if micro is 0, i.e. "1.0.0" and "1.2.0" not "1.0"/"1.2"
+
+ - "make distcheck" (DO NOT just "make dist" - pass the check!)
+
+ - if make distcheck fails, fix it.
+
+ - once distcheck succeeds, "cvs commit"
+
+ - if someone else made changes and the commit fails,
+ you have to "cvs up" and run "make distcheck" again
+
+ - once the commit succeeds, "cvs tag DBUS_X_Y_Z" where
+ X_Y_Z map to version X.Y.Z
+
+ - bump the version number up in configure.in, and commit
+ it. Make sure you do this *after* tagging the previous
+ release! The idea is that CVS has a newer version number
+ than anything released.
+
+ - scp your tarball to freedesktop.org server and copy it
+ to /srv/dbus.freedesktop.org/www/releases. This should
+ be possible if you're in group "dbus"
+
+ - update the wiki page http://www.freedesktop.org/Software/dbus by
+ adding the new release under the Download heading. Then, cut the
+ link and changelog for the previous that was there.
+
+ - update the wiki page
+ http://www.freedesktop.org/Software/DbusReleaseArchive pasting the
+ previous release. Note that bullet points for each of the changelog
+ items must be indented three more spaces to conform to the
+ formatting of the other releases there.
+
+ - post to dbus@lists.freedesktop.org announcing the release.
+
+After making a ".0" stable release
+===
+
+After releasing, when you increment the version number in CVS, also
+move the ChangeLog to ChangeLog.pre-X-Y where X-Y is what you just
+released, e.g. ChangeLog.pre-1-0. Then create and cvs add a new empty
+ChangeLog. The last entry in ChangeLog.pre-1-0 should be the one about
+"Released 1.0".
+
+Add ChangeLog.pre-X-Y to EXTRA_DIST in Makefile.am.
+
+We create a branch for each stable release; sometimes the branch is
+not done immediately, instead it's possible to wait until someone has
+a not-suitable-for-stable change they want to make and then branch to
+allow committing that change.
+
+The branch name should be DBUS_X_Y_BRANCH which is a branch that has
+releases versioned X.Y.Z
+
+To branch, tag HEAD with DBUS_X_Y_BRANCHPOINT:
+ cvs tag DBUS_X_Y_BRANCHPOINT
+then create the branch from that tag:
+ cvs rtag -b -r DBUS_X_Y_BRANCHPOINT DBUS_X_Y_BRANCH dbus
+
+Note that DBUS_X_Y_BRANCHPOINT may not tag the same revision as the
+DBUS_X_Y_0 release, since we may not branch immediately.
+
+Environment variables
+===
+
+These are the environment variables that are used by the D-Bus client library
+
+DBUS_VERBOSE=1
+Turns on printing verbose messages. This only works if D-Bus has been
+compiled with --enable-verbose-mode
+
+DBUS_MALLOC_FAIL_NTH=n
+Can be set to a number, causing every nth call to dbus_alloc or
+dbus_realloc to fail. This only works if D-Bus has been compiled with
+--enable-tests.
+
+DBUS_MALLOC_FAIL_GREATER_THAN=n
+Can be set to a number, causing every call to dbus_alloc or
+dbus_realloc to fail if the number of bytes to be allocated is greater
+than the specified number. This only works if D-Bus has been compiled with
+--enable-tests.
+
+DBUS_TEST_MALLOC_FAILURES=n
+Many of the D-Bus tests will run over and over, once for each malloc
+involved in the test. Each run will fail a different malloc, plus some
+number of mallocs following that malloc (because a fair number of bugs
+only happen if two or more mallocs fail in a row, e.g. error recovery
+that itself involves malloc). This env variable sets the number of
+mallocs to fail.
+Here's why you care: If set to 0, then the malloc checking is skipped,
+which makes the test suite a heck of a lot faster. Just run with this
+env variable unset before you commit.
+
+Tests
+===
+
+These are the test programs that are built if dbus is compiled using
+--enable-tests.
+
+dbus/dbus-test
+This is the main unit test program that tests all aspects of the D-Bus
+client library.
+
+dbus/bus-test
+This it the unit test program for the message bus.
+
+test/break-loader
+A test that tries to break the message loader by passing it randomly
+created invalid messages.
+
+"make check" runs all the deterministic test programs (i.e. not break-loader).
+
+"make check-coverage" is available if you configure with --enable-gcov and
+gives a complete report on test suite coverage. You can also run
+"test/decode-gcov foo.c" on any source file to get annotated source,
+after running make check with a gcov-enabled tree.
+
+Patches
+===
+
+Please file them at http://bugzilla.freedesktop.org under component
+dbus, and also post to the mailing list for discussion. The commit
+rules are:
+
+ - for fixes that don't affect API or protocol, they can be committed
+ if any one qualified reviewer other than patch author
+ reviews and approves
+
+ - for fixes that do affect API or protocol, two people
+ in the reviewer group have to review and approve the commit, and
+ posting to the list is definitely mandatory
+
+ - if there's a live unresolved controversy about a change,
+ don't commit it while the argument is still raging.
+
+ - regardless of reviews, to commit a patch:
+ - make check must pass
+ - the test suite must be extended to cover the new code
+ as much as reasonably feasible
+ - the patch has to follow the portability, security, and
+ style guidelines
+ - the patch should as much as reasonable do one thing,
+ not many unrelated changes
+ No reviewer should approve a patch without these attributes, and
+ failure on these points is grounds for reverting the patch.
+
+The reviewer group that can approve patches: Havoc Pennington, Michael
+Meeks, Alex Larsson, Zack Rusin, Joe Shaw, Mikael Hallendal, Richard
+Hult, Owen Fraser-Green, Olivier Andrieu, Colin Walters, Thiago
+Macieira, John Palmieri.
+
+