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
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).
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.
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").
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
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.
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
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.
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
Openbravo ERP development guide that includes all the documentation on how to develop extensions
