From bb189fdb75947870ad72b44bd3225b394b7a7a9d Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Tue, 14 Jul 2009 22:35:11 +0200 Subject: Update the HACKING file to contain instructions on how we develop with Git --- HACKING | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 92 insertions(+), 6 deletions(-) diff --git a/HACKING b/HACKING index f765866c..3a981ae2 100644 --- a/HACKING +++ b/HACKING @@ -59,12 +59,95 @@ Coding Style 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 CVS + - 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 @@ -85,21 +168,24 @@ To make a release of D-Bus, do the following: - if make distcheck fails, fix it. - - once distcheck succeeds, "git-commit -a". This is the version + - 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" + - 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". + 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. - - push your changes to the central repository with "git-push" + - 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 new tag, too: "git-push origin dbus-X.Y.Z" + - 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 -- cgit