We'd love to have you contribute by hacking on the bindings themselves!
- Checkout the source code
If you're going to hack seriously with, or on, java-gnome, we recommend the following sequence to checkout the source code:
$ cd ~/src/
$ mkdir java-gnome/
$ git clone git://github.com/afcowie/java-gnome.git working
$ cd working/
$ less README.markdown
If you are using Eclipse, you may instead want to do this such that the
checkout is under ~/workspace
.
$ cd ~/workspace/
$ git clone git://github.com/afcowie/java-gnome.git java-gnome
$ cd ~/workspace/java-gnome/
$ less README.markdown
Doing it this way allows you to later do
$ git checkout 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.
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.
The java-gnome 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.
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
java-gnome 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.
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.
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.
There are just a few minor conventions you should be aware of when committing
patches. See doc/style/CommitMessages
.
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.
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
.
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 22 Feb 13