diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/HACKING b/HACKING new file mode 100644 index 00000000..f1e9d765 --- /dev/null +++ b/HACKING @@ -0,0 +1,341 @@ +The guidelines in this file are the ideals; it's better to send a +not-fully-following-guidelines patch than no patch at all, though. We +can always polish it up. + +Mailing list +=== + +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: + + - avoid memcpy(), sprintf(), strlen(), snprintf, strlcat(), + strstr(), strtok(), or any of this stuff. Use DBusString. + If DBusString doesn't have the feature you need, add it + to DBusString. + + There are some exceptions, for example + if your strings are just used to index a hash table + and you don't do any parsing/modification of them, perhaps + DBusString is wasteful and wouldn't help much. But definitely + if you're doing any parsing, reallocation, etc. use DBusString. + + - do not include system headers outside of dbus-memory.c, + dbus-sysdeps.c, and other places where they are already + included. This gives us one place to audit all external + dependencies on features in libc, etc. + + - do not use libc features that are "complicated" + and may contain security holes. For example, you probably shouldn't + try to use regcomp() to compile an untrusted regular expression. + Regular expressions are just too complicated, and there are many + different libc's out there. + + - we need to design the message bus daemon (and any similar features) + to use limited privileges, run in a chroot jail, and so on. + +http://vsftpd.beasts.org/ has other good security suggestions. + +Coding Style +=== + + - The C library uses GNU coding conventions, with GLib-like + extensions (e.g. lining up function arguments). The + Qt wrapper uses KDE coding conventions. + + - Write docs for all non-static functions and structs and so on. try + "doxygen Doxyfile" prior to commit and be sure there are no + warnings printed. + + - All external interfaces (network protocols, file formats, etc.) + should have documented specifications sufficient to allow an + alternative implementation to be written. Our implementation should + be strict about specification compliance (should not for example + heuristically parse a file and accept not-well-formed + data). Avoiding heuristics is also important for security reasons; + if it looks funny, ignore it (or exit, or disconnect). + +Development +=== + +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. + +- 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 + + - 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 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, "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 unannotated tag: "git tag dbus-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 git has a newer version number + than anything released. + + - merge the branch you've released to the chronologically-later + branch (usually "master"). You'll probably have to fix a merge + conflict in configure.in (the version number). + + - push your changes and the tag to the central repository with + git push origin master dbus-X.Y dbus-X.Y.Z + + - scp your tarball to freedesktop.org server and copy it + to /srv/dbus.freedesktop.org/www/releases/dbus. 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 git, 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: + git branch dbus-X.Y-branch +and upload the branch tag to the server: + git-push origin dbus-X.Y-branch + +To develop in this branch: + git-checkout dbus-X.Y-branch + +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 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 (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> + + |