Developer Guidelines


These are the guidelines for developers on the openJean open source project.
Current contributors to this document are Vicki Sivess and Mike Curtis.

The openJean Community

We are hoping to bring together a community of users and developers who will work together to improve openJean to the benefit of the whole community. We ask that anyone joining the project be respectful of others' views and courteous in all their interactions. We hope to foster an atmosphere of trust and we hope that this will be a very exciting project to work on.
As yet we do not have a governing body or a formal management structure. This will be put into place when necessary. The project is managed by Mike Curtis, author of openJean. He is happy to help and advise anyone wanting to get involved.

Mailing Lists

There are three mailing lists which anyone involved with openJean should join. One of these is for developers and one is for users. The third list is to enable all email commits to be distributed to all developers. We ask that all developers join this list and we hope that it will help foster a sense of involvement. You can reply with a comment but the reply-to has been set up so that such comments will be redirected to the developers' list.

IRC Channel

The channel #openJean has been set up on chat.freenode.net to enable users and developers of openJean to communicate more easily with each other. In order to access this, you will need an IRC client on your machine. Information can be found on the http://freenode.net website.
Times for question and answer sessions with project developers will be posted on the project website.

Criteria for Acceptance

Anyone who wants to join the project as a developer is welcome. Any suggested code for bug fixes or new features should be emailed to Mike who will, when appropriate, grant you commit access.
Once the project has a number of developers with commit access, we will set up proper procedures to nominate developers to be committers.
As well as technical competence, the most important attributes for people with commit access are common sense and a knowledge of where your strengths and weaknesses lie.

Coding Standards


Building openJean

The README file from latest stable download contains details of how to build openJean. A copy of this is held in the openJean documentation on Sourceforge.

Using CVS

All code is under the CVS version control system on Sourceforge. Eventually we plan to hold all documentation such as manuals and all the web pages there. Emails for all commits to CVS are sent to the openjean-commits mailing list.

Defect Fixing

We use the Tracker system on Sourceforge for bug reporting and feature requests. At present we do not use the patches option, and ask that any suggested patches are for now mailed directly to Mike.
The bug categories relate to the available openJean catalogs: AddressBook, Images etc. There are also four Framework categories for bugs that relate to the whole of openJean and not just one specific catalog. These subcategories are Database, User Interface, Performance and Miscellaneous. The category Framework:Miscellaneous should be used as a catch-all for defects that cannot be categorised elsewhere. The three final categories are Utilities, Website and Documentation for any errors and bugs detected there.
The bug groups relate to the version of openJean you are using: for example, v0.9.1.
One of the administrators will set the priority of the defect and change any mis-categorisation. They will also look out for duplicate reportings of the same bug. You can help in this by first checking through existing bug reports for this group. It may be that the problem has been fixed and that you can get a corrected version from the CVS system.
At present all bug reports for openJean are directed to Mike to fix, and bugs in the Website or documentation are assigned to Vicki. As more developers join the project and develop expertise in different areas, we hope this list will be expanded.
The status of a bug will initially be set to open. When it has been fixed (or if it cannot be fixed) it will be set to closed. Occasionally we will set the status to pending if we are awaiting specific feedback from the original reporter of the bug.
The categories for Feature Requests are similar and the groups are Next Release and Some Future Release depending upon how important you feel the suggested feature is. These requests will all be assigned to Mike.

Releasing openJean



Some Important Files

XML Files

Item.node, group.node and category.node


Information about attributes for items, groups and categories is found in the three XML files item.node, group.node and category.node. These three files are stored in the relevant folder for each catalog in the applications folder. For instance, on a Windows system, the three files pertaining to the AddressBook catalog are conventionally kept in the folder
C:\Documents and Settings\<username>\jean\applications\addressBook. Any time an attribute is created or deleted, using the openJean:SDK, one of these files will be updated as appropriate. Alternatively, you can bypass the SDK and edit them directly yourself.

As an example we will look at the item.node file for addressBook. This starts with information about the namespace, in this case addressBook:

<jean:node xmlns:jean="http://www.mullsoft.co.uk/jean" jeanid="-3" name="&lt;unknown&gt;"
namespace="addressBook"
type="item">
<jean:pagedAttributeSet name="&lt;unknown&gt;" namespace="addressBook">
Then follows a series of attributeSets, one for each page. The following lines:

<jean:attributeSet editable="false" name="Identity" namespace="addressBook" ordinal="0"
visible="true">
<jean:description>Please enter the name of this person or company. For a company the company name should be put into the &lt;i&gt;Last name&lt;/i&gt;field.</jean:description>

introduce the Identity page, and contain the text displayed in the create wizard for the page. This is followed by information about each attribute on that page. For example, the following lines describe the title attribute. It is an enumeration type with the values listed, and the value Mr. is the default.

<jean:attribute name="title" ordinal="0" persistence="persistent" prompt="Title"
readOnly="false"
required="false"
system="false"
type="enumeration(Mr.|Ms.|Mrs|Miss|Dr.|Prof.| |Rev.)"
visible="true">Mr.</jean:attribute>

The openJean distribution comes with the three files item-original.node, group-original.node and category-original.node. These should not be changed in case you need to reset to the original version.

application.xml

This file, found in the same folder, contains information about the locations of the methods corresponding to the operations in the menu for that catalog. Many of these, such as Create new item have default methods which can be overridden. Once again, application.xml is changed automatically by certain operations of the SDK, or it can be changed directly by the programmer.

Each jean:attribute line contains the name of the operation as it appears in the menu. E.g. name="EditAlbum" in Multimedia. The line then ascribes an ordinal number to this menu item, as ordinal="6", which controls the order in which the entries appear. Usually you can just take the next ordinal number up from the last one used. If you leave a gap in the numbers, a horizontal rule will appear in the menu. In this way, menu items can be grouped together. The location of the method is then shown, as in uk.co.mullsoft.multimedia.MultimediaUtilities.editAlbum. Most user-defined methods are located in the <catalog name>Utilities file.

Node files


All information held in openJean catalogs is stored in node files. The node files store values for the attributes and any forward and backward links. These should on no account be changed directly. If you mouse over any node in the catalog, you will see its number, and that is the name of that particular node file. For example, node 123 is stored in 123.node. All node files are stored in subfolders of the folder called nodes. For example in Windows the nodes for AddressBook will usually be found in subfolders of
C:\Documents and Settings\<username>\jean\applications\addressBook\nodes.