1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
We'd love to have you contribute by hacking on the bindings themselves!
GETTING STARTED
===============
1. 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.
### And build!
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.
TECHNICAL DETAILS
=================
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.
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
java-gnome bindings. Try starting with
[`doc/design/START`](doc/design/START.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/),
opening GTK and GNOME to Java programmers!
_Last modified 22 Feb 13_
<!--
Copyright © 2006-2013 Operational Dynamics Consulting, Pty Ltd and Others
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 its
authors as open source software: you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 ("GPL") as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GPL for more details.
You should have received a copy of the GPL along with this program. If not,
see http://www.gnu.org/licenses/. The authors of this program may be
contacted through http://java-gnome.sourceforge.net/.
vim: set textwidth=78:
-->
|
