You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
201 lines
7.0 KiB
201 lines
7.0 KiB
14 years ago
|
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 message-bus-list@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).
|
||
|
|
||
|
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
|
||
|
|
||
|
- 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.
|
||
|
|
||
|
- "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!
|
||
|
|
||
|
- scp your tarball to freedesktop.org server and copy it
|
||
|
to /srv/dbus.freedesktop.org/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.
|
||
|
|
||
|
|
||
|
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.
|
||
|
|
||
|
|