Contributing to java-gnome

We’d love to have you contribute by hacking on the bindings themselves!

GETTING STARTED

1. Checkout the source code

We are using Bazaar to manage our source code. More commonly known as bzr, it is an advanced third-generation Distributed Version [or Revision] Control System. It’s a good idea to have a recent version (ie bzr >= 1.18).

If you’re going to hack seriously with, or on, java-gnome, we recommend the following sequence to checkout the source code:

$ cd ~/src/
$ bzr init-repository java-gnome/
$ cd java-gnome/
$ bzr checkout bzr://research.operationaldynamics.com/bzr/java-gnome/mainline/ mainline/
$ bzr branch mainline/ working/
$ cd working/
$ less README

This will result in a local copy of ‘mainline’ which you can use to track upstream and to diff against, and ‘working’ as new branch for you to play with. :) The branch will be at (in this example) ~/src/java-gnome/working/. All branches under ~/src/java-gnome/ will share storage of revisions, so you won’t pay any penalty for creating as many branches as you like.

If you are using Eclipse, we recommend creating a branch in your Workspace and using that to work on. This will allow you to relatively easily change branches while not screwing up all your launchers.

$ cd ~/workspace/
$ bzr checkout ~/src/java-gnome/working java-gnome
$ cd ~/workspace/java-gnome/
$ less README

Doing it this way allows you to later do

$ bzr switch some-other-branch

to change between branches you have created with different lines of development. This works well, but is an advanced layout, so do experiement with it a bit if you aren’t well versed in distributed version control practises.

And build!

If you haven’t already read them, see the instructions in the top level README for how to install from a source tarball and what options you can supply to the ./configure script.

Why bzr?

We chose Bazaar (Bazaar-NG, as it was briefly known) as the VCS for the Java bindings for GNOME because of its relative straight-forwardness and because of our faith in the ethos and extreme competence of its developers. Anyone experienced with the old world 1st generation centralized VCS tools like CVS or Subversion will be able to make sense of it and you can learn from there. Bazaar is constantly improving in performance terms, has a vibrant developer community, is widely portable. Most of all, the fact that the people hacking on bzr itself actually follow test-driven-development practises (their unit test suite has over 15,000 tests!) keeps them honest and conclusively biases in their favour.

In production use for the last three years, we have found Bazaar to be reliable, amazingly easy for newcomers to the Open Source world to learn, and a significant element in our effort to reduce barriers to entry.

We reiterate that you must use a recent version of Bazaar. There is nothing intrinsically better about older software; bug fixes and performance improvements are not back-ported by the people who write the code; they release a new version instead. If your operating system does not provide >= 1.18 then you would do well to install bzr manually.

2. Do your own thing!

The amazing thing about the decentralized VCS tools is that you do not need to be online to make commits. But it’s more than that — you don’t need to be me to make commits! You can work away on your own branch(es) and then send your patches in already committed form to me for consideration and merging.

Make sure to identify yourself first:

$ bzr whoami 'George Jones <grjones@example.com>'

before committing the first time — see setting your user ID.

A day in the life of a java-gnome hacker

As you are working, you can see what you have done with:

$ bzr status
$ bzr diff

then, when you are happy with a piece of work, commit:

$ bzr commit

You can do this one or more times.

There is a vitally important point, however: no one can tell you you can’t work on something. And of you want to share it, go right ahead. That said, if you’d like to see your work merged into the mainline and available publicly in the official releases, then we’d encourage you to follow the stylistic guidelines discussed out below.

Staying up to date

Meanwhile, you’ll want to catch-up with what’s been going on upstream. So update the checkout you have of mainline with the following:

$ cd ../mainline
$ bzr update

Then you need to merge in the upstream changes into your branch:

$ cd ../working
$ bzr merge

Merging only brings the changes to your working directory; it doesn’t commit them to your working branch. So, assuming you want to accept them, you need to do a commit of those changes. So, Look at the changes that were pulled in with:

$ bzr status
$ bzr diff

then commit:

$ bzr commit

but make sure you only commit the stuff you’ve merged in, not unfinished changes you’ve might have locally! In other words, best to do the merge after you’ve finished anything you might happen to be doing in that branch.

To send a patch

If you’ve done some work on your local branch and you’d like to contribute it, go ahead and commit it locally in your working branch, then try the following:

$ bzr bundle ../mainline > /tmp/name-that-tune.patch

This will output a human readable diff along with the actual revisions in a safely encoded form into the file you specify. Just attach that file to an email and send it along. .patch is a good suffix because most mail clients know to set the MIME type of such an attachment properly.

TECHNICAL DETAILS

The java-gnome 4.0 bindings are pretty straight forward, so in terms of adding new coverage you can probably pick things up by example fairly easily. But you really should take the time to understand why things work, or you won’t be able to understand the mechanisms involved behind the scene.

API design and overall system architecture

In the doc/design/ subdirectory you will find extensive documentation of the current re-engineering process that lead to the design and architecture of the new java-gnome 4.0 bindings. Try starting with doc/design/START.

You really are encouraged to peruse these files; the one on Architecture in particular is pretty much required reading if you want to understand what’s going on.

STYLE GUIDE

Things like how you format your code, what editor you use, etc are all very personal issues, but for a project to function with anything even remotely resembling sanity, there need to be some standards and conventions. Thus we have several documents outlining the style guidelines you’ll need to know if hacking on the java-gnome 4.x bindings. They’re in the doc/style/ directory.

Code formatting

I’ve carefully documented the 4 divergences from the otherwise default “Java conventions” for Java source code formatting. Please take a moment to read doc/style/CodeFormat; your patches have a much better chance of being accepted if they produce clean diffs, and that’s more likely to happen if you stick to these rules.

Commit Messages

There are just a few minor conventions you should be aware of when committing patches. See doc/style/CommitMessages.

Documentation

JavaDoc is the heart and soul of our API documentation and good JavaDoc is going to be the key defining criteria for our bindings being approachable to new developers. As such we’ve written out considerable guidance about how to best go about documenting our public APIs.

Of course, JavaDoc alone isn’t sufficient, and we have a number of supporting documents describing the design and architecture of java-gnome. See doc/style/Documentation for discussion of appropriate style for both in-code JavaDoc and supporting textual Design documentation.

Markup

We have gone to considerable trouble to ensure our text documentation files are readable from a terminal window, but by using a simple yet powerful markup syntax called Markdown we can also easily render these files to useful web pages. See doc/style/MARKUP.

CONCLUSION

The opportunity to work on something you love is the greatest experience you can have. If you or your company chooses to offer code you write, be it towards helping us on this project or on any other endeavour whatsoever, I encourage you to choose to let others use your work as Software Libre and in your own turn help people find their own passion and excitement. By your actions you lift us all up. I hope you’ll join us!

Apotheosis Rising.

AfC

--
Andrew Frederick Cowie
Managing Director,
Operational Dynamics,
a Change Management consultancy…

Maintainer,
java-gnome,
opening GTK and GNOME to Java programmers!

Last modified 8 Feb 09