X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;ds=sidebyside;f=HACKING;h=805fd2e00de22cfbef8f1ffdd73529abc60ac009;hb=16ed767007722d7450e6f5a4e23fff0166f466dc;hp=40377cc0b9c34b2cdb50d68c032228d63ee9d7c9;hpb=6ec04e917c8b4d477e818aa65ebb5e1fd50e4395;p=platform%2Fupstream%2Fdbus.git diff --git a/HACKING b/HACKING index 40377cc..805fd2e 100644 --- a/HACKING +++ b/HACKING @@ -5,13 +5,13 @@ can always polish it up. 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. @@ -59,40 +59,141 @@ Coding Style 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. + +- 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. + - - check out a fresh copy from CVS +Making a release +=== - - increment the version number in configure.in +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 - - 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"; 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. - - if someone else made changes and the commit fails, - you have to "cvs up" and run "make distcheck" again + - 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". - - 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.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)". - - 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" + - 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). + + - 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 + 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" + + - Update the online documentation with `make -C doc maintainer-upload-docs`. - update the wiki page http://www.freedesktop.org/Software/dbus by adding the new release under the Download heading. Then, cut the @@ -104,29 +205,62 @@ To make a release of D-BUS, do the following: items must be indented three more spaces to conform to the formatting of the other releases there. - - post to dbus@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 +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 +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 +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 +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 === @@ -134,7 +268,7 @@ 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 +This is the main unit test program that tests all aspects of the D-Bus client library. dbus/bus-test @@ -144,12 +278,15 @@ 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. +"make lcov-check" is available if you configure with --enable-compiler-coverage +and gives a complete report on test suite coverage. Patches === @@ -169,10 +306,24 @@ rules are: - 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 + 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, @@ -180,8 +331,21 @@ rules are: 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. - - +The reviewer group that can approve patches: + +Havoc Pennington +Michael Meeks +Alexander Larsson +Zack Rusin +Joe Shaw +Mikael Hallendal +Richard Hult +Owen Fraser-Green +Olivier Andrieu +Colin Walters +Thiago Macieira +John Palmieri +Scott James Remnant +Will Thompson +Simon McVittie +David Zeuthen