Contributing to the JavaRosa Code Base

TracNav(JavaRosaTOC) The JavaRosa code base is large, and identifying just how and where to add a contribution to the code can be difficult. Luckily, JavaRosa is designed with a modular architecture, and many common changes can be done easily by designing them to fit into the modular framework. This document details some of the most common (and beneficial) additions you may make to the code, and walks you though building them into JavaRosa.

Prerequisites

Read the [wiki:GettingStarted Getting Started] guide about how to set up the build environment and properly contribute code.

Read the [wiki:SourceManagement Source Management] guidelines before checking in any code. In particular, make sure to run all unit tests before committing to ensure you have not inadvertently broken any functionality.

Finally, many unfamiliar terms from the JavaRosa universe are explained in the [wiki:Glossary JavaRosa Glossary].

Creating New Modules

'''''[wiki:NewModule Full guide]'''''

If you're adding genuinely new functionality to JavaRosa (as opposed to extending existing functionality), it is likely you will have to create a new module. For our purposes, 'module' is synonymous with an eclipse project -- a collection of closely related source files to implement a particular feature. 'Modules' are largely an issue of how code is organized in the source tree, and can be integrated in a uniform manner by implementing and using the IModule interface.

Note: we try to sequester code that is dependent on a particular platform (Like J2ME or J2ME Polish) from code that is not. Dependent and non-dependent code should go in separate modules.

Creating New Activities

'''''[wiki:NewActivity Full guide]'''''

The most common contribution will be creating new Activities. You should create a new Activity whenever you want to create a unique and specific 'interaction' with the user. Activities are a small nugget of UI, and should be specific enough in scope such that they can be easily rearranged and used within other workflows. Any moderately complex interaction with the user will likely involve several activities working together. For example, choosing a form, choosing a saved instance of that form to edit, editing the form, and sending the results are all separate activites.

Should an Activity stand alone as its own project/module, or be added to an existing module? In general, if an activity is only useful in the context of the other activities in a project, it should go in the same project. All the form-related activites mentioned above, for example, inhabit the same project.

If you could reasonably use activity but not another, it makes sense for them to be in different projects. A form list may exist independently of a login screen, and vice versa, for instance. This separation is especially important when one of the activities can't be run on a certain device.

Creating New Services

'''''[wiki:NewService Full guide]'''''

Services mediate the communication between the JavaRosa core and external resources. A camera, GPS, network sockets, and persistent storage (file, RMS, etc.) are all examples of resources provided by services. Services exist so that the code JavaRosa code need not know about the messy device-dependent details about accessing these resources. They are also meant to handle the possibility that some resources aren't available on certain devices at all.

A new service will almost always deserve its own module.

Improvements to Existing Code

We should strive to maintain high standards for the JavaRosa code. Code should exhibit fail-fast behavior and as much type safety as is practicable within the J2ME/JavaRosa architecture.

However, JavaRosa isn't developed in a vacuum, and occasionally real-world deadlines trump developers' ability to write the best code possible. Cleaning up poorly/hastily written code is an extremely valuable contribution you can make. Larger refactoring efforts are also welcomed, but be sure to wait until you're intimately familiar with the code to be refactored and coordinate with all developers it may affect.

Searching for TODO flags in the code comments is a good way of finding these places that need attention. You can also consult 'Wishlist' tickets. Or just ask a developer.

Creating New Software Applications Using the JavaRosa Platform

'''''[wiki:NewApplication Full guide]'''''

Creating a new application that uses the JavaRosa platform is a valuable contribution. Not only does it contribute lots of new functionality, but it provides a new end-to-end user experience that demonstrates JavaRosa's ability to tackle diverse problem domains.

Here 'application' means all the new Activities and Services needed to run the application, as well as a new master Shell that coordinates the overall workflow.

The key point to stress is '''modularity'''. Properly isolate your new features as reusable components that other JavaRosa applications can take advantage of. Ideally, the only 'custom code' for your application is the Shell that coordinates all the pieces working together.

Creating New Tests

'''''[wiki:UnitTesting Full guide]'''''

With so many developers working on different parts of the JavaRosa code for different purposes, they will inevitably step on each other's toes and break something they didn't intend to. Testing is important for our project because it will catch such problems quickly.

So far our focus is unit-level testing; there is still much of the code base to be tested. Writing new tests for the code is unbelievably helpful. You can use existing tests as a reference.

Any new development should be accompanied by the associated tests.

Creating New Chatterbox Widgets

'''''[wiki:NewWidget Full guide]'''''

Extending the Chatterbox (our Polish-based form entry interface) can be complicated, but there are standard interfaces for adding new UI widgets that you can use when filling out a form. You can place your custom widget in org.javarosa.polish.chatterbox.extensions, but if your widget is contextually related to another project, it may be more logical to include it there. That said, a project should not be dependent on Polish or Chatterbox unless it cannot conceivably be used with any other interface.