Using Openbravo Forge to develop extensions

Introduction

This post describes the best practices and polices to apply in Openbravo Forge to develop and organize an extension. These are a simplified version of the same guidelines that we use to develop Openbravo ERP core project plus some specific guidelines for the Openbravo Forge usage.

Let's start by defining some key concepts:

• Module: provides an atomic functionality. Examples of modules are reports, connectors, functional extensions, etc.
• Pack: group all the modules necessary to enable Openbravo ERP for a mean. For example, a vertical pack that collects all the modules required to enable Openbravo ERP for a specific industry.
• Template: a configuration file plus a collection of packs and modules
  

Documentation

Before starting any development, we recommend to create a set of documentation that will guide the development and will help users in the future to understand what the module achieves.

We recommend to have the following documentation:

• A Main Page that serves as an entry point to the projects' documentation and describes its objective and links to the related documentation.
• A Functional Specification that describes the functional requirements, use cases and other documentation that describe the needs that the module is willing to cover.
• A Technical Documentation that covers all the technical aspects to be taken into consideration when developing the module (such as database structure, etc).
  

You can take a reference the Human Capital Module to better understand how to organize this documentation.

Source Control System

Developers can use the source control system of their choice. Openbravo Forge provides Subversion as source control system. The instructions given in this section apply only to Subversion, including the recommended repository structure for Openbravo modules. You can leverage on your source control system specific features for branching and tagging.

The following is a list of common terminology used when working with Subversion:

Subversion client. Software run by a user to access a Subversion server also called Subversion repository.

• Subversion repository. The Subversion server stores a copy of the files of the project. The server retains both the most recent version and every historical version (past changes). * Trunk. Development with Subversion progresses similar to a tree. The main development occurs against the trunk.
• Branch. A split of development off of the trunk or another branch. Branches allow developments to diverge either permanently or temporarily.
• Tag. A tag or label refers to an important snapshot in time, consistent across many files. These files at that point may all be tagged with a user-friendly, meaningful name or revision number.
  

Recommended Repository Structure for Openbravo Modules

Openbravo recommends following structure when organizing the source code of your module:

project_name
* tags
* trunk
* branches

When developing a module, the main development activity occurs in the main development trunk.

All developers commit the changes against this branch. When a version is reach, a tag should be done.

If you want to work with a stable version you usually download the tagged version (a released version) and if you want to follow the development you download trunk.

We recommended the Version Control with Subversion free on-line book.

Registering Modules

As a prerequisite to publish modules into the Central Repository, you have to first register them.

This a list of recommendations when registering modules within the Central Repository from Openbravo ERP:

Use the field help to give precise instructions on how to use the module once is installed. For example, the required steps to access it from Openbravo ERP menu.

• Do not leave the URL field in blank, provide the project's web where users can find more information about your product.
• Do not leave the author's field in blank. It should be clear to the user who the author is.
• Package name. Use the standard package name naming conventions from Java, for example com.yourcompany.project. The package name org.openbravo is reserved for Openbravo as a company.
• If you are registering a module, use the same Single Sign-on username to register and then to associate it.
• Do not use the name of the client in the code or in the module definition
• It is fine to develop in other languages than English but the language of the module must be set accordingly
• If the module has been tested only in one database (Oracle or PostgreSQL), you might want to add that as a note in the module description ("This module should be data base independent; however it has been tested only on Oracle | PostgreSQL").
  

Creating Packs
Packs
When creating a pack project in Openbravo Forge, we recommend to enable the following services in Openbravo Forge:

• Module: to publish the pack in the central repository
• Forums: to discuss issues for the functionality that the pack targets
• Wiki: to document the configuration and link to the rest of the resources
  

We suggest to discard the usage of the rest of the services that the Forge provides.

Additionally, we recommend:

• Since a pack groups modules, they should not contain code, and as result, they should not require a source control system.
• We recommend to report issues, using the bug tracking system, to each particular module instead of reporting to a pack.
• We only recommend to publish files in the download area during the development cycle, you post your obx file in progress in the download area for early adopters to download and evaluate. We do not recommend to publish the files in the download service once they are released since you can already download files published in the central repository.
• When registering the project, assign it to the Openbravo ERP -> Packs category.
  

Module

When creating a module in Openbravo Forge, we recommend to enable the following services:

• Module: to publish the module in the central repository
• Code: to develop the code of the module and be able to work in a collaborative manner with other developers
• Bug Tracking: to allow users to report issues or functionality enhancements
• Wiki: to document the configuration and link to the rest of the resources
  

For modules, we suggest to discard the usage of the rest of the services that the Forge provides.

Additionally, we recommend:

• We only recommend to publish files in the download area during the development cycle, you post your obx file in progress in the download area for early adopters to download and evaluate. We do not recommend to publish the files in the download service once they are released since you can already download files published in the central repository.
• When registering the project, assign it to the Openbravo ERP -> Modules category.
  

Template

A template is a configuration file plus a collection of packs and modules. We recommend to enable the following services in Openbravo Forge:

• Module: to publish the template in the central repository
• Code: to develop the configuration file
• Forums: to discuss about the template
• Bug Tracking: to track issues with the configuration file
• Wiki: to document the configuration and link to the rest of the resources
  

Additional Information

Openbravo ERP development guide that includes all the documentation on how to develop extensions

Contributing to Openbravo ERP QA efforts

Introduction

Quality Assurance is key for having successful software products. Openbravo projects follow an open development process that allows everybody to take part in any part of the development process. Let me describe how you can get involved in the Quality Assurance processes for Openbravo ERP.

Before getting started we recommend that you read the following documents to get familiar with the main Openbravo development concepts and processes:

• Development Process Management. Describes the Openbravo development process from a management perspective.
• Openbravo Releases. Describes Openbravo releases and versions.
  

Openbravo testing methodologies

At Openbravo the following testing methodologies are combined to assurance the product's quality:

• Test cases: These area a set of well defined steps, execution preconditions, and expected results to exercise a particular program scenario or to verify compliance with a specific requirement. For managing test cases TestLink is used.
• Automated testing at Openbravo to automate the testing of Openbravo ERP using test cases.
• Unit testing using pieces of code that verify that functionality of different Openbravo ERP components. Currently in early stage using JUnit.
  

How you can help

Testing early releases

In the Openbravo ERP Early Releases Discussion forum we announce new alpha and beta versions that people can help to test.

Things that you can do to help:

• Verify that bugs that this release addresses have been fixed.
• Executing test cases to make sure that the functionality works.
• Test the new functionality and make sure that works properly.
• Reporting new issue introduced in this release.
  

Reporting issues on any version

Have you found a bug? Please, report it to us using our bug database. Make sure that you carefully read our Bug Reporting Guidelines before submitting your bug report.

Contributing test cases

For every release of Openbravo, at Openbravo's TestLink you have the collection of cases that are executed to verify the compliance of requirements. These test cases focus on assurance the coverage of the major use cases but not all the cases.

You can contribute by providing new test cases that you think that are important for Openbravo to include as part of our test plan (collection of cases) for every release or also cases that you think are critical for a specific module, industry or market segment.

Reaching Openbravo QA team

• Early Releases Discussion forum
• IRC chat channels
• Openbravo's QA blog
  

Tools

• Openbravo Issues. Openbravo bug tracking & enhancements database.
• Openbravo Code. Contains all the Openbravo ERP source code controls.
• Automated build farm. Openbravo continuous integration system.
• Openbravo's TestLink. Openbravo case management tool.
• Continuous Integration for Openbravo ERP.
  

Openbravo Forge User Manual available

We have published the final version of the Openbravo Forge User Manual. The manual covers the basic usage of the Openbravo Forge and its aimed to help project administrators and users on their daily use of the Forge.

The manual contains an introduction to the Forge and the services that provides, a detailed explanation of how to register projects, how users can fine tune their settings and how to use the Forge to develop, communicate and publish projects. We recommend this manual to all users using the Forge and to people willing to learn more about its capabilities.

If you have any question regarding the Openbravo Forge, do not hesitate to ask it on the Openbravo Forge forum.

Using Openbravo Forge to develop an Openbravo ERP localization

Hello there,

One of the earliest adopters of the Openbravo Forge since it was launched two months ago have been the localizers. They appreciate the freedom of been able to setup their project, forums and been able to publish news, files and modules in the Central Repository (before it was necessary our assistance).

In the last weeks of experience working with localization projects on the Forge we have crafted some best practices and polices to apply in Openbravo Forge to develop and organize a localization project.

Let me share them with you.

Introduction

Many countries and regions have similar requirements, like sharing the same language or functional requirement. To be able to reuse localization components, we provide the following types of projects to enable functionality delivery:

• Module: provides an atomic functionality. Examples of modules are chart of accounts, translations, banking interfaces, etc.
  
• Pack: group all the modules necessary to enable Openbravo ERP for a country or region. For example, the Spain Localization Pack that contains a full localization package for Spain.
  

We recommend that:

• Each country or region should create one and only one pack that contains all the relevant modules. A pack should be created for consistency sake even if it contains only one module.
• Each country or region could create zero or more modules (zero if it only reuses modules and does not create any geography specific modules)
  

Packs

When registering your localization pack project for your region, we recommend to enable the following services in Openbravo Forge:

• Module: to publish the pack in the central repository
• Forums: to discuss localization issues for the region that the pack targets

For localization packs, we suggest to discard the usage of the rest of the services that the Forge provides.

Additionally, we recommend:

• Since a pack groups modules, they should not contain code, and as result, they should not require a source control system.
• We recommend to report issues, using the bug tracking system, to each particular module instead of reporting to a pack.
• We only recommend to publish files in the download area during the development cycle, you post your obx file in progress in the download area for early adopters to download and evaluate. We do not recommend to publish the files in the download service once they are released since you can already download files published in the central repository.
• When registering the project, assign it to the 'Openbravo ERP -> Localization Packs category.

Modules

When registering your localization modules, we recommend to enable the following services:

• Module: to publish the module in the central repository
• Code: to develop the code of the module and be able to work in a collaborative manner with other developers
• Bug Tracking: to allow users to report issues or functionality enhancements
• Wiki:to publish documentation for the project and to coordinate work
  

For localization modules, we suggest to discard the usage of the rest of the services that the Forge provides.

Additionally, we recommend:

• We only recommend to publish files in the download area during the development cycle, you post your obx file in progress in the download area for early adopters to download and evaluate. We do not recommend to publish the files in the download service once they are released since you can already download files published in the central repository.
• When registering the project, assign it to the 'Openbravo ERP -> Localization Modules category.
  

Project naming conventions

For naming localization projects we recommend the format Name of the country + Description, except for language modules that we recommend Language name + for + country.

For example, for Spain we use the following names:

Pack

• Spain Localization Pack. Contains all the modules necessary to apply the localization for Spain.
  

Modules

• Spain Chart of accounts - General. Contains the Spanish translation for Spain
• Spain Taxes. Contains the definition of taxes for Spain.
• Spanish for Spain. Contains the Spanish translations customized for Spain.
  

Package name conventions

The following table contains a description of the best practices when naming packages.


Additional links

• Localization process. Recommendations on how to structure packs and develop modules.
• Openbravo ERP localization forum for discussing and getting help on Openbravo ERP related localization issues.
  

Openbravo Wiki Archive namespace

Openbravo Wiki has currently more than 2.000 articles. Many of these articles are legacy documents that belong to older versions of our projects: user manuals, design documents, old coordination documents, etc. A search in Openbravo Wiki returns as results many legacy documents that are no longer useful making more challenging for users to find the information that they are looking for. With the new categorization system, that was introduced some weeks back, the situation has improved since categories are more usable but there is still room for improvement.

To address this situation, we have created the Openbravo Wiki archive namespace. We have started to move all the articles that we consider legacy to this new namespace. The idea is to keep in the main namespace only documentation that is valid for the current stable version, Openbravo ERP R2.50 nowadays. Additionally, we have modified the search UI for Openbravo Wiki enhance the search user experience.

I think that these changes will improve greatly the experience of all users looking for information.

I want also mention that creation of new categories has been blocked. This has been done to prevent the proliferation of categories that ignored our current category system. Please, contact the Wiki administrators if you need a new category.

Openbravo Forge chat meeting on Monday 11st of May 2009

Since the launch of Openbravo Forge a little more than a month ago, we have received lots of questions and ideas. During the Openbravo World Conference lots of people had questions on how the Forge can help them to be more productive and get more exposure on what they do, something that I briefly explained a few days back.

I would like to organize a chat with all of you to discuss about the Forge. Mainly to:

• To solve doubts regarding the usage of the Openbravo Forge that you may have
• Questions on how to develop verticals and extensions through the Forge
  
• To answer questions regarding future plans of the Openbravo Forge
• To get Feedback and ideas for future versions
  

The details are of the chat are:

Date: Monday 11st of May at 14.00 GMT + 1 (16.00 local time in Spain due to daylight savings). Check the World Clock if you want to check the time in your area.
Where: IRC Network FreeNode at the #openbravo channel
Language: English

I will appreciate if you can participate in the meeting if you have ideas or questions about the Forge.

Openbravo World Conference 2009 presentations available

The presentations of the Openbravo World Conference 2009 have been just published.

There are also some pictures available from the event.

Enjoy!