[jsword-devel] JSword collaboration opportunities

[DM Smith]

Everyone,

We now have an open area for collaboration, called incubator. You can 
find it under svn here:
    http://www.crosswire.org/svn/jsword/trunk/incubator

Create Eclipse projects under this location. For example, if you are 
creating a RCP version of Common, create a plugin project:
    http://www.crosswire.org/svn/jsword/trunk/incubator/common

As I make changes and apply patches to Common and JSword, I'll try to 
keep these in sync and run what ever JUnit tests you provide.

Feel free to comment as this is our community.

Everyone has permission to read and write code in this area and because 
of that we need some simple guidelines.
1) Always provide a short message when doing a checkin. It does not have 
to be elaborate but should suggest what you are doing.
2) Always prefix the short message with your name, initials or something 
by which we know it is you. Because everyone has read/write permission 
all checkins are anonymous and show up as being done by "Apache".
3) Always prefix the file with JSword's standard license statement: for 
GUI code, the license is GPL. For library code it is LGPL. Licenses of 
borrowed code must be compatible with these and those licenses are 
retained on the borrowed code. Lots of opportunity for more 
clarification/discussion as the need arises.
4) If you are the author of the code, include it in the file with the 
following pattern: @author DM Smith [dmsmith555 at yahoo dot com]. Also 
add your @author to the bottom of the list if you made a significant 
contribution. But not if your change was minor.
5) For each project provide an Ant build.xml so that it can be built 
from a command line on the crosswire server.

Coding Guidelines:
1) Use Checkstyle, FindBugs, PMD, shared Eclipse Java coding style rules 
to maintain code quality and consistency.
2) Write JUnit tests for new classes and new behavior.
3) Don't unnecessarily change code. Consider a Bridge Pattern, if needed.
4) Focus on good design and correctness early. Optimize late.
5) Code to interfaces with minimal coupling. For example, in adding an 
"sermon outline" capability, create a Outline interface which does not 
know about Jobs or Progress but does know about the things that pertain 
to Outlines.
6) Minimize code duplication. It may be better to wrap the existing 
JSword implementation than to duplicate it. It may be better to change 
JSword or Common than to fork either. Before creating a fork, lets 
discuss it to see if there is a better way.

RCP opportunities:
1) OSGi: JSword uses interfaces to define fundamental behavior and 
factories to deliver that behavior. The factories use a custom mechanism 
for obtaining the behavior. In some factories we allow for only one 
behavior, but some allow for more than one. These would be a perfect 
candidate for using the OSGi plugin model. Note: it is possible to use 
this without incurring the cost of the entire RCP.
2) Persistence: This is one of the most requested features for 
BibleDesktop. The basic idea is that the application would start where 
it left off. We have put this off because it is a core capability of RCP.
3) Configuration: Common provides an ability for an application (in this 
case BibleDesktop) to provide options to the user. This consists of 
model, controller (common project) and view code (common-swing). RCP 
provides a much more complete and mature mechanism.
4) Progress: RCP provides a robust progress mechanism. No sense in 
having duplication.
5) Jobs: RCP provides a job mechanism. Again duplication should be avoided.

BibleDesktop GUI opportunities:
Once we have a stable RCP implementation for JSword and Common we can 
entertain writing a SWT/JFace version of BibleDesktop:
1) Browser: The HTML rendering of Swing is terribly primitive. It is 
desirable to use a robust HTML browser. This was our initial reason for 
looking at SWT. It has robust broswer capabilities that let us do 
everything that we currently do (i.e. intercept urls with novel 
protocols, i.e. bible:// with a custom handler) and it allows us to do 
anything else we can't currently do. While this has nothing to do with 
RCP, it is still a primary motivation for going to RCP.
2) Adaptable UI: Different users have different workflows. The user 
should be able to arrange the UI to suit their own needs. One user might 
want a simple daily devotion. Another a robust search engine. Another 
works from left to right, while another from top to bottom.
3) Additional Behavior: One of the hallmarks of RCP is the ability for 
new behavior to be added without disturbing the existing code base. A 
developer should be able to add a new behavior to JSword or 
BibleDesktop, such as blogging or sermon preparation, without the 
overhead of knowing all the ins and outs or JSword. And a user should be 
able to pick and choose from behaviors that are available, incurring the 
cost of a behavior only if they choose it.

Other UI Targets:
1) PDA/phone/handheld: A very desirable goal, but currently JSword and 
Common have code that is outside the J2ME set of classes. We should work 
in a fashion that makes this goal more attainable, not less. If someone 
would like to survey JSword and Common for
2) Web applications: These could take many forms, for an example, see 
http://eireneh.com/studious