1
We'd love to have you contribute by hacking on the bindings themselves!
6
1. Checkout the source code
7
---------------------------
9
If you're going to hack seriously with, or on, java-gnome, we recommend the
10
following sequence to checkout the source code:
14
$ git clone git://github.com/afcowie/java-gnome.git working
16
$ less README.markdown
18
If you are using Eclipse, you may instead want to do this such that the
19
checkout is under `~/workspace`.
22
$ git clone git://github.com/afcowie/java-gnome.git java-gnome
23
$ cd ~/workspace/java-gnome/
24
$ less README.markdown
26
Doing it this way allows you to later do
28
$ git checkout some-other-branch
30
to change between branches you have created with different lines of
31
development. This works well, but is an advanced layout, so do experiement
32
with it a bit if you aren't well versed in distributed version control
37
If you haven't already read them, see the instructions in the top level
38
[`README`](README.html) for how to install from a source tarball and what
39
options you can supply to the `./configure` script.
45
The java-gnome bindings are pretty straight forward, so in terms of adding
46
new coverage you can probably pick things up by example fairly easily. But you
47
really should take the time to understand *why* things work, or you won't be
48
able to understand the mechanisms involved behind the scene.
50
API design and overall system architecture
51
------------------------------------------
53
In the `doc/design/` subdirectory you will find extensive documentation of the
54
current re-engineering process that lead to the design and architecture of the
55
java-gnome bindings. Try starting with
56
[`doc/design/START`](doc/design/START.html).
58
You really are encouraged to peruse these files; the one on Architecture in
59
particular is pretty much required reading if you want to understand what's
65
Things like how you format your code, what editor you use, etc are all very
66
personal issues, but for a project to function with anything even remotely
67
resembling sanity, there need to be some standards and conventions. Thus we
68
have several documents outlining the style guidelines you'll need to know if
69
hacking on the java-gnome 4.x bindings. They're in the `doc/style/` directory.
74
I've carefully documented the 4 divergences from the otherwise default "Java
75
conventions" for Java source code formatting. Please take a moment to read
76
[`doc/style/CodeFormat`](doc/style/CodeFormat.html); your patches have a much
77
better chance of being accepted if they produce clean diffs, and that's more
78
likely to happen if you stick to these rules.
83
There are just a few minor conventions you should be aware of when committing
84
patches. See [`doc/style/CommitMessages`](doc/style/CommitMessages.html).
89
JavaDoc is the heart and soul of our API documentation and good JavaDoc is
90
going to be *the* key defining criteria for our bindings being **approachable**
91
to new developers. As such we've written out considerable guidance about how
92
to best go about documenting our public APIs.
94
Of course, JavaDoc alone isn't sufficient, and we have a number of supporting
95
documents describing the design and architecture of java-gnome. See
96
[`doc/style/Documentation`](doc/style/Documentation.html) for discussion of
97
appropriate style for both in-code JavaDoc and supporting textual Design
103
We have gone to considerable trouble to ensure our text documentation files are
104
readable from a terminal window, but by using a simple yet powerful markup
105
syntax called Markdown we can also easily render these files to useful web
106
pages. See [`doc/style/MARKUP`](doc/style/MARKUP.html).
112
The opportunity to work on something you love is the greatest experience you
113
can have. If you or your company chooses to offer code you write, be it
114
towards helping us on this project or on any other endeavour whatsoever, I
115
encourage you to choose to let others use your work as Software Libre and in
116
your own turn help people find their own passion and excitement. By your
117
actions you lift us all up. I hope you'll join us!
124
Andrew Frederick Cowie
126
[Operational Dynamics](http://www.operationaldynamics.com/),
127
a Change Management consultancy...
130
[java-gnome](http://java-gnome.sourceforge.net/),
131
opening GTK and GNOME to Java programmers!
133
_Last modified 22 Feb 13_
137
Copyright © 2006-2013 Operational Dynamics Consulting, Pty Ltd and Others
139
As project documentation, this file forms an integral part of the source
140
code of the library it accompanies, and thus is made available to you by its
141
authors as open source software: you can redistribute it and/or modify it
142
under the terms of the GNU General Public License version 2 ("GPL") as
143
published by the Free Software Foundation.
145
This program is distributed in the hope that it will be useful, but WITHOUT
146
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
147
FITNESS FOR A PARTICULAR PURPOSE. See the GPL for more details.
149
You should have received a copy of the GPL along with this program. If not,
150
see http://www.gnu.org/licenses/. The authors of this program may be
151
contacted through http://java-gnome.sourceforge.net/.
153
vim: set textwidth=78:
added
removed
HACKING.markdown
