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
+Development
===
-To make a release of D-BUS, do the following:
+D-Bus uses Git as its version control system. The main repository is
+hosted at git.freedesktop.org/dbus/dbus. To clone D-Bus, execute the
+following command:
+
+ git clone git://git.freedesktop.org/dbus/dbus
+OR
+ git clone git.freedesktop.org:dbus/dbus
+
+The latter form is the one that allows pushing, but it also requires
+an SSH account on the server. The former form allows anonymous
+checkouts.
+
+D-Bus development happens in two branches in parallel: the current
+stable branch, with an even minor number (like 1.0, 1.2 and 1.4), and
+the next development branch, with the next odd number.
+
+The stable branch is named after the version number itself (dbus-1.2,
+dbus-1.4), whereas the development branch is simply known as "master".
+
+When making a change to D-Bus, do the following:
+
+ - check out the earliest branch of D-Bus that makes sense to have
+ your change in. If it's a bugfix, it's normally the current stable
+ branch; if it's a feature, it's normally the "master" branch. If
+ you have an important security fix, you may want to apply to older
+ branches too.
+
+ - for large changes:
+ if you're developing a new, large feature, it's recommended
+ to create a new branch and do your development there. Publish
+ your branch at a suitable place and ask others to help you
+ develop and test it. Once your feature is considered finalised,
+ you may merge it into the "master" branch.
- - check out a fresh copy from CVS
+- for small changes:
+ . make your change to the source code
+ . execute tests to guarantee that you're not introducing a
+ regression. For that, execute: make check
+ (if possible, add a new test to check the fix you're
+ introducing)
+ . commit your change using "git commit"
+ in the commit message, write a short sentence describing what
+ you did in the first line. Then write a longer description in
+ the next paragraph(s).
+ . repeat the previous steps if necessary to have multiple commits
- - increment the version number in configure.in
+ - extract your patches and send to the D-Bus mailing list for
+ review or post them to the D-Bus Bugzilla, attaching them to a bug
+ report. To extract the patches, execute:
+ git format-patch origin/master
+
+ - once your code has been reviewed, you may push it to the Git
+ server:
+ git push origin my-branch:remote
+ OR
+ git push origin dbus-X.Y
+ OR
+ git push origin master
+ (consult the Git manual to know which command applies)
+
+ - (Optional) if you've not worked on "master", merge your changes to
+ that branch. If you've worked on an earlier branch than the current
+ stable, merge your changes upwards towards the stable branch, then
+ from there into "master".
+
+ . execute: git checkout master
+ . ensure that you have the latest "master" from the server, update
+ if you don't
+ . execute: git merge dbus-X.Y
+ . if you have any conflicts, resolve them, git add the conflicted
+ files and then git commit
+ . push the "master" branch to the server as well
+
+ Executing this merge is recommended, but not necessary for all
+ changes. You should do this step if your bugfix is critical for the
+ development in "master", or if you suspect that conflicts will arise
+ (you're usually the best person to resolve conflicts introduced by
+ your own code), or if it has been too long since the last merge.
+
+
+Making a release
+===
+
+To make a release of D-Bus, do the following:
+
+ - check out a fresh copy from Git
- 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 file NEWS based on the git history
+
+ - verify that the version number of dbus-specification.xml is
+ changed if it needs to be; if changes have been made, update the
+ release date in that file
+
+ - update the AUTHORS file with "make update-authors" if necessary
+
+ - 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"; the micro
+ version should be even for releases, and odd for intermediate snapshots
- "make distcheck" (DO NOT just "make dist" - pass the check!)
- if make distcheck fails, fix it.
- - once distcheck succeeds, "cvs commit"
+ - once distcheck succeeds, "git commit -a". This is the version
+ of the tree that corresponds exactly to the released tarball.
+
+ - tag the tree with "git tag -s -m 'Released X.Y.Z' dbus-X.Y.Z"
+ where X.Y.Z is the version of the release. If you can't sign
+ then simply created an unsigned annotated tag:
+ "git tag -a -m 'Released X.Y.Z' dbus-X.Y.Z".
+
+ - bump the version number up in configure.ac (so the micro version is odd),
+ and commit it. Make sure you do this *after* tagging the previous
+ release! The idea is that git has a newer version number
+ than anything released. Similarly, bump the version number of
+ dbus-specification.xml and set the release date to "(not finalized)".
+
+ - merge the branch you've released to the chronologically-later
+ branch (usually "master"). You'll probably have to fix a merge
+ conflict in configure.ac (the version number).
- - if someone else made changes and the commit fails,
- you have to "cvs up" and run "make distcheck" again
+ - push your changes and the tag to the central repository with
+ git push origin master dbus-X.Y dbus-X.Y.Z
- - once the commit succeeds, "cvs tag DBUS_X_Y_Z" where
- X_Y_Z map to version X.Y.Z
+ - scp your tarball to freedesktop.org server and copy it to
+ dbus.freedesktop.org:/srv/dbus.freedesktop.org/www/releases/dbus/dbus-X.Y.Z.tar.gz.
+ This should be possible if you're in group "dbus"
- - check out the "web" module, copy the tarball to
- web/content/software/dbus/releases, "cvs add -kb dbus-x.y.z.tar.gz"
+ - Update the online documentation with `make -C doc maintainer-upload-docs`.
- - update web/content/software/dbus/main.in with a pointer to the
- tarball
+ - 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 message-bus-list@freedesktop.org announcing the release.
+ - post to dbus@lists.freedesktop.org announcing the release.
+
+Making a ".0" stable release
+===
+
+We create a branch for each stable release. The branch name should be
+dbus-X.Y which is a branch that has releases versioned X.Y.Z;
+changes on a stable branch should be limited to significant bug fixes.
+
+Because we won't make minor changes like keeping up with the latest
+deprecations on a stable branch, stable branches should turn off the
+gcc warning for deprecated declarations (e.g. see commit 4ebb275ab7).
+
+Be extra-careful not to merge master (or any branch based on master) into a
+stable branch.
+
+To branch:
+ git branch dbus-X.Y
+and upload the branch tag to the server:
+ git push origin dbus-X.Y
+
+To develop in this branch:
+ git checkout dbus-X.Y
+
+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.
+
+test/name-test/*
+This is a suite of programs which are run with a temporary session bus.
+If your test involves multiple processes communicating, your best bet
+is to add a test in here.
+
+"make check" runs all the deterministic test programs (i.e. not break-loader).
+
+"make lcov-check" is available if you configure with --enable-compiler-coverage
+and gives a complete report on test suite coverage.
+
+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.
+
+ - at their discretion, members of the reviewer group may also commit
+ branches/patches under these conditions:
+
+ - the branch does not add or change API, ABI or wire-protocol
+
+ - the branch solves a known problem and is covered by the regression tests
+
+ - there are no objections from the rest of the review group within
+ a week of the patches being attached to Bugzilla
+
+ - the committer gets a positive review on Bugzilla from someone they
+ consider qualified to review the change (e.g. a colleague with D-Bus
+ experience; not necessarily a member of the reviewer group)
+
+ - 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 (see Tests above)
+ - 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 <hp@pobox.net>
+Michael Meeks <michael.meeks@novell.com>
+Alexander Larsson <alexl@redhat.com>
+Zack Rusin <zack@kde.org>
+Joe Shaw <joe@assbarn.com>
+Mikael Hallendal <micke@imendio.com>
+Richard Hult <richard@imendio.com>
+Owen Fraser-Green <owen@discobabe.net>
+Olivier Andrieu <oliv__a@users.sourceforge.net>
+Colin Walters <walters@verbum.org>
+Thiago Macieira <thiago@kde.org>
+John Palmieri <johnp@redhat.com>
+Scott James Remnant <scott@netsplit.com>
+Will Thompson <will.thompson@collabora.co.uk>
+Simon McVittie <simon.mcvittie@collabora.co.uk>
+David Zeuthen <davidz@redhat.com>
projects / platform / upstream / dbus.git / blobdiff