This document provides comprehensive software development processes tailored for open source projects. It covers processes, conventions, and recommended tools. The guide aims to help developers quickly get up to speed with best practises.

You are not expected to read this guide cover-to-cover. You probably should be familiar with the contents and reference the appropriate section when you need it. Documentation aims to be concise with references elsewhere on the web for details like installation instructions.

This guide is written in a modular fashion so that different projects can easily add, delete, or modify sections. It is hoped that this guide will become the de-facto standard software developers guide for java based open source projects.

For this guide to be useful it needs to be continually added to and improved as tools are developed, processes improved and projects grow. Please consider improving or adding a section if you feel it is required.

Ideally, all recommended tools would be open source, however we have included some no-cost tools where there are gaps in the open source tool set. Where applicable, widely accepted conventions and open standards are used. It has been satisfying to discover the breadth of quality open source tools which support software development. It is hoped that this document will highlight areas where tools can be improved or developed and encourage developers to focus on these areas.

This section should be replaced and explain your project.

This project contains Javascript code which requires XML functions. In order to run these functions you will require generation 6 browsers. Ie, Internet Explorer 6 or Netscape 6 or greater.

Concurrent Versions System (CVS) is a version control system that allows multiple developers to work on the same files at the same time.

Information on how to download and edit this project's source code are provided at: http://sourceforge.net/cvs/?group_id=35246.

Note, before you can edit files, you will need to be granted write access from the Community Map Builder Project Management Committee.

An excellent CVS manual can be found at http://cvsbook.red-bean.com/.

This section describes the terms used when building a release. This section is explained in more detail at https://sourceforge.net/docman/display_doc.php?docid=6445&group_id=1#componentoverview.

Release version numbers are based on 3 main digits and an optional release candidate digit : <major>.<minor>.<patch>-rc<release candidate>. It looks like 2.3.4 or 2.3.4-rc5 .

For projects that use maven, the version number is stored in the <currentVersion> tag in maven's project.xml file.

To do: We need to discuss the meaning of:

Every time the version number is incremented, you need to tag the relevant files in the repository. This ensures that previous releases can be recreated for future debugging.

Tag names are based on the module version and look like <package_name>-<major>_<minor>_<patch>-rc<release candidate>. Eg: generguide-lib-2_3_4-rc5 .

Note that full stops from the version number are replaced with underscores. This is because CVS doesn't allow full stops in tags.

Typically, you would create a release tag with the following statements in CVS:

cd mapbuilder
cvs tag generguide-lib-2_3_4

This section describes the steps to follow when building a release.

Users are the people who use the products of the Project. People in this role aren't contributing code, but they are using the products, reporting bugs, making feature requests, and such. This is by far the most important category of people as, without users, there is no reason for the Project.

When a user starts to contribute code or documentation patches, they become a Contributor.

Contributors are the people who write code or documentation patches or contribute positively to the project in other ways. A volunteer's contribution is always recognized. In source code, all volunteers who contribute to a source file may add their name to the list of authors for that file.

Contributors who give frequent and valuable contributions to a subproject of the Project can have their status promoted to that of a "Committer" for that subproject. A Committer has write access to the source code repository and gains voting rights allowing them to affect the future of the subproject.

In order for a Contributor to become a Committer, another Committer can nominate that Contributor or the Contributor can ask for it.

Once a Contributor is nominated, all existing committers will vote. If there are at least 3 positive votes and no negative votes, the Contributor is converted into a Committer and given write access to the source code repository. This is an example offer letter that should be sent to the volunteer after 3 positive votes have been received:

Committers are asked to coordinate their efforts with the maintainers of the modules they wish to modify/extend.

At times, Committers may go inactive for a variety of reasons. A Committer that has been inactive for 6 months or more may lose their status as a Committer. Getting access back is as simple as re-requesting it on the project's Developer mailing list.

Committers who frequently participate with valuable contributions may have their status promoted to that of a Project Management Committee Member. This committee is the official managing body of the Project and is responsible for setting overall project direction. In order to become a Member, someone on the PMC must nominate the Committer. The individual may then be approved with a 3/4 majority of the PMC.

Email lists provide an effective form of communication. Details about this project's email lists can be found at: http://sourceforge.net/mail/?group_id=35246.

Javascript files need to be uploaded across potentially slow internet connections. Consequently, it is desirable to keep file sizes to a minimum.

Javascript files can be compressed with The Creativyst CSS and JavaScript Compressor.

To do: Find an open source compression algorithm. The above algorithm removes white spaces and comments, but does not compress file names, which could reduce file size even more.

A design document should provide a brief overview of the design to help developers gain a quick understanding of the system. The design documentation is enhanced by using more diagrams and less text.

Text in the design document should be written in docbook format. Refer to the documentation section for more details about using docbook.

Documentation about procedures and classes should be embedded in the source code and then extracted into Detailed Design documentation using an external parser.

UML is a standard notation used to specify, visualise, construct and document the components of an object-oriented software-intensive system. UML diagrams are used as part of design documentation.

Directory names shall be all lower case with no spaces. Some versions of windows do not distinguish between upper and lower case, and in unix, writing spaces in filenames is painful.

to do: need to fill out this section.

This quick start section will get you editing simple docbook sections quickly and easilly. For more detailed information, refer to the rest of the documentation section.

Documentation for this project is written using Simplified Docbook format. Simplified Docbook is a subset of Docbook XML, a versatile format used by the Linux Documentation Project (among others).

Docbook can be easily converted into numerous output formats, like HTML, PDF, etc.

Using Docbook ensures documentation content is kept separate from presentation so content can written once and published in numerous formats and styles.

There are a few GUI editors for docbook now, with more editors promising to support docbook in the future.

According to The Software Release's Howto, docbook is the open source format of the future, and most of the high profile open source projects have moved or are moving to docbook as their coding standards. So we are saving ourselves pain in the future by embracing Docbook now.

Modular DocBook means content is broken up into smaller file modules that are recombined for publication. The advantages of modular documentation include:

This project uses modular documents for it's documentation.

If you want to document a new module, you need to write a new module.xml section file, and then add an <xi:include> tag into design.xml.

Notice in the above example that <section> tags contain an id attribute. This means the URL of published sections will be human readable, something like http://net.sourceforge.generguide/docs/design.html#licence instead of http://net.sourceforge.generguide/docs/design.html#id2754172.

You can edit docbook with the following free tools:

There are a few references worth knowing: