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.

If you're going to hack on the bindings, we recommend that you do the
following:

    $ bzr init-repo --trees java-gnome
    $ cd java-gnome
    $ bzr checkout http://research.operationaldynamics.com/bzr/java-gnome/mainline
    $ bzr branch mainline working
    $ cd working
    $ ./configure
    $ make

This will create two branches, a `java-gnome/mainline/`, which is a checkout
that you can use to track upstream, and a `java-gnome/working/`, which is a
full power branch. This second one is your playground. `:)`

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

### Why `bzr`?

We have chosen `bzr` for its relative straight forwardness and because of our
faith in the ethos of its developers. Anyone used to using 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. While Bazaar could be a lot perkier
in terms of its responsiveness, and it still has a number of rough edges, it
is improving rapidly. The fact that it has a vibrant community, is widely
portable, and most of all that the development team actually have an enormous
unit test suite to keep them honest biases in their favour.

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.

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.

### "General maintenance"

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/patch-name.patch

This will output the diffs, along with a whole spew of Bazaar metadata, into
the file you specify. It's 7 bit safe, so you can just attach that file to an
email and it will be able to be merged by others. `.patch` is a good suffix
because most mail clients know to do something useful with such an attachment.


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/README`](doc/design/README.html).

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`](doc/style/CodeFormat.html); 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`](doc/style/CommitMessages.html).

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`](doc/style/Documentation.html) 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`](doc/style/MARKUP.html).


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](http://www.operationaldynamics.com/),  
a Change Management consultancy...

Maintainer,  
[java-gnome](http://java-gnome.sourceforge.net/4.0/),  
opening GTK and GNOME to Java programmers!

_Last modified 11 Dec 06_

<!--

  Copyright (c) 2006 Operational Dynamics Consulting Pty Ltd 

  As project documentation, this file forms an integral part of the source
  code of the library it accompanies, and thus is made available to you by the
  authors under the terms of the "GNU General Public Licence, version 2". See
  the LICENCE file for the terms governing usage, copying and redistribution.

  vim: set textwidth=78 nowrap:

-->
