ERP/2.40/Openbravo Development Environment ODE

Introduction

Important note: this document applies to versions 2.35 and 2.40 of Openbravo ERP (Openbravo ERP 2.50 development environment).

Openbravo Development Environment (abbreviated as ODE) is a framework of tools, methodologies and processes to make Openbravo ERP development process easier and to help developers to be more efficient in tasks such as editing source code, debugging, testing, deploying and managing code repositories. ODE supports Oracle and PostgreSQL based on environments. ODE is designed to support the development process for whatever the intent is (Openbravo ERP core contributions, modules and custom code) and whatever the scope is (from small bug fixes to complete new functional modules).

Document explanation

One of the primary goals for ODE is to use open and popular (de-facto standard) tools and practices whenever it is possible. Some of the tools that ODE is based on are Apache Ant, Eclipse IDE and Subversion. Concepts section introduces these tools which are required to understand how ODE performs. You can skip this section if you are familiar with these tools.

Next section after concepts Openbravo ERP source code structure is described: sub-projects within Openbravo ERP source code and folder structure for each of them. After that there is a further explanation about the way Openbravo manages database source code that is a central part of ODE and is done in a very innovative and elegant way.

Next section is a guide addressed to developers about how to perform all the development tasks such as building from sources or committing changes to the repository. You can skip this section if you just want to overview Openbravo Development Environment.

The next two sections explains specifics about the three possible development intents: Openbravo ERP core contributions, modules and custom code.

Finally the last section describes how to migrate to ODE from previous releases.

Concepts

Ant

Apache Ant is a Java-based build tool. Openbravo automates most of its development tasks using Ant. For more general or technical information concerning Apache Ant, please visit:

• Apache Ant's manual.
• Apache Ant's Frequently Asked Questions (FAQ).
• Apache Ant's Wiki.

Eclipse IDE

Eclipse is an open-source Integrated Development Environment (IDE) written primarily in Java. To benefit from this tool, Openbravo ERP's latest source code has been modified to work with Eclipse's IDE projects schema.

If you plan to use this tool, please make sure that you properly install and setup Eclipse IDE for Openbravo ERP development before going on. For more general or technical information concerning Eclipse IDE, please visit:

• Eclipse Newcomers Frequently Asked Questions (FAQ).
• Eclipse's Getting Started resources.
• Eclipse's documentation.

Subversion (SVN)

Subversion (abbreviated as SVN) is the version control system (VCS) used at Openbravo. Subversion provides the means to store not only the current version of a piece of source code, but a record of all changes (and who made those changes) that have occurred to that source code. Use of Subversion is particularly common on projects with multiple developers, since this tool ensures that developments made by one developer are not accidentally overwritten when another one adds its own developments to the source code tree.

For more general or technical information concerning Subversion, please visit:

• Source Control How-To by Eric Sink.
• A Visual Guide to Version Control by BetterExplained.com.
• Version Control with Subversion free on-line book.
• Subversion's Frequently Asked Questions (FAQ).

Development cycle

In general words, a collaborative software development process consists of six steps: check out, build, test, changes, update and commit. Openbravo ERP source code (including database structure and metadata information) is now entirely made of plain text files and can be completely managed following a standard development cycle where steps mix in an iterative process that ends when requirements are achieved.

1. Check out is the action of downloading the last revision from a source code repository.
2. Build source code by compiling it and linking the resulting files.
3. Test the resulting application to ensure that your development does not lead to errors nor lost of functionalities. For this purpose, please feel free to follow Openbravo ERP acceptance tests.
4. Change the source code to add new features or modify existing ones. Then, you will have to compile it and test the application again.
5. Update your source code with the last revision of the source code repository.
6. Commit your source code changes once you tested that all works properly.

Common Subversion terminology

The following is a list of common terminology used when working with Subversion. Please notice that some of these definitions have been extracted from Revision control Wikipedia article.

• 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 ERP repository tree structure consists of:

• Revision: A revision or version is one version in a chain of changes. A versioned file belongs to a particular version.
• Head revision: is the last source code revision downloaded to your machine from the source code repository.
• Working copy: is the local copy of repository's source code. That is the code a developer works on.
• Check-out: A check-out creates a local working copy from the repository. Either a specific revision is specified, or the latest is obtained.
• Update: An update merges changes that have been made in the repository (e.g., by other developers) into the local working copy.
• Commit: A commit (check-in) occurs when a copy of the changes made to the working copy is written or merged into the repository.
• Revert: In order to resolve any conflicted state, revert any file or directory modified locally to a previous revision of it.
• Merge: A merge or integration brings together two sets of changes to a file or set of files into an unified revision of that file or files.
  • This may happen when one user, working on those files, updates their working copy with changes made, and checked into the repository, by other users. Conversely, this same process may happen in the repository when a user tries to commit their changes.
  • It may happen after a set of files has been branched, then a problem that existed before the branching is fixed in one branch and this fix needs merging into the other.
  • It may happen after files have been branched, developed independently for a while and then are required to be merged back into a single unified trunk.
• Conflict: A conflict occurs when two changes are made by different parties to the same document, and the system is unable to reconcile the changes. A user must resolve the conflict by combining the changes, or by selecting one change in favour of the other.

Required software

To be able to work with a Subversion repository you need a Subversion client software.

Openbravo ERP source code structure

Openbravo ERP source code structure has been divided into five projects (feel free to browse detailed folder structure):

• src-core Source code of the MVC framework: XmlEngine (View), SQLC (Model), HttpBaseServlet (Controller) and so on.
• src-trl Source code of the static content translator.
• src-wad Source code of WAD (Wizard for Application Dictionary).
• src-db Source code to manage database source code based on Apache DdlUtils.
• src Source code of Openbravo ERP itself: forms, reports, call-outs, combos, work-flows, processes and so on.

Openbravo ERP database source code has been transformed into *.xml files inside database folder. This change allows a much simpler management and update of database structure and data. This feature is explained in further detail in next section.

• model: database schema objects (tables, views, functions, triggers and sequences).
• sourcedata: metadata information needed to describe Openbravo ERP elements (windows, tabs and fields, tables and columns, processes and so on).
• sampledata: sample data (products, business partners, invoices and so on) to be able to play with Openbravo ERP. These sample data might be deleted when Openbravo ERP is used for production purposes.

Configuration files have been unified.

• Openbravo.properties file, inside config folder, includes database information, URL context information, date formats and so on.

Database code management

Introduction

Openbravo ERP source code is made of two different types of code: MVC code (Java, HTML, xSQL, JavaScript, CSS, ... files) and database code. Database code can be separated into DDL statements of database schema objects (tables, views, triggers,...) and Application Dictionary (AD) metadata': records in AD tables such as AD_Window or AD_Column. When Openbravo application is installed, a database (Oracle or PostgreSQL) is created by executing the DDL statements, metadata is inserted and MVC code is compiled. Once the database is created custom data is added to the database such as products, business partners or invoices information. That data is stored by the database in binary files mixed with schema objects and AD metadata.

New developments (bug fixes or new features) usually include changes in both MVC and database code. There are two major problems with the generic exported database dump, especially when wanting to include one in a source code repository:

• It is not easy to get a detailed and clean description of your development changes since the dump (*.dmp) file is a binary file and not a text one. Hence, diff statement does not work well on binary files.
• It is not possible to update a production environment by deploying the changes in the source code. Instead, a database script needs to be prepared that performs the alter and update statements required in order to keep customer data that is already in the database.

DdlUtils

DdlUtils is a small, easy-to-use component by Apache Foundation for working with Database Definition (DDL) files. These are XML files that contain the definition of the database schema (e.g., tables and columns). These files can be feed into DdlUtils via its Ant task or programmatically in order to create or alter the corresponding database so that it corresponds to the DDL. In the same way, DdlUtils can generate a DDL file from an existing database. Openbravo has extended some DdlUtils capabilities (for instance, support for check constraints, procedures and views; PL/SQL translation from Oracle to PostgreSql; support for more database types, ...) and fine tune others (for instance, export database schema objects, ...) to fully support ODE requirements.

How it works

Each Openbravo ERP system (working copy - AppsOpenbravo) has a folder called database where all the database source code (schema objects and AD metadata) are stored in plain *.xml text files. Source code in database folder is divided into:

• model (schema objects such as tables, functions, etc.),
• sourcedata (AD metadata in tables AD_Table, AD_Window, etc.)
• sampledata (custom data for testing purposes such as business partners, products and so on).

ODE includes tasks to synchronize the database folder content and the database itself. Changes to the database code can happen to one or the other:

• In the database folder (working copy):
  • Through updates coming from the SVN repository. When changes come from a SVN update, they do not overwrite changes done in the working copy since these changes are merged in corresponding files.
  • In PostgreSQL environments, developers have to modify schema objects by editing database source code in the database/model folder.
• Inside the database:
  • Editing the AD metadata using the Openbravo ERP Application Dictionary windows and processes.
  • In Oracle environments, performing changes to schema objects (tables, columns, procedures and so on) using your CASE tool for database management.

ODE provides the following tasks to synchronize the database source code within the database folder with the database itself:

• create.database task: first reads schema objects *.xml files inside database/model folder and creates schema objects in database itself. After that, this task fills these schema objects with AD metadata and sample data taken from database/sourcedata and database/sampledata folders, respectively. Keep in mind that this task recreates the database from scratch which means that an existing database will first be dropped!
• update.database task: compares the schema objects and AD metadata with the database source code in the database folder and the database itself. Differences are applied to the database, keeping customer data in database untouched.
• export.database task: takes schema objects and AD metadata from database and overwrites database source code inside the database/model and database/sourcedata folders, respectively.

As you can imagine, whenever any of these tasks are executed, both database models (the one in database folder and the database itself) are forced to be identical. The first two tasks modify the database so that it is equal to database folder content and the third one changes the database folder content to equal the database.

In summary, the database folder contains Openbravo ERP database source code clearly separated from customer data. This way, the database is not distributed as a binary dump file anymore.

Because changes to the database can happen within the text files or the database itself, it is extremely important to guarantee that these changes do not happen simultaneously to both sides because this situation would lead to system inconsistency and loss of data. This is guaranteed by using a check based on the SVN revision number. Each time create.database or update.database tasks are launched, revision number of the working copy is saved to the database. export.database task checks that the revision number of the working copy matches with the revision number of the database. If it matches, there is a guarantee that changes in the database will not overwrite changes done by other developers. If it does not, the developer will get an error and will be forced to switch the working copy to the current database revision number.

Other auxiliary tasks available to track the changes to the database:

• compare.database.structure: compares database model (schema objects) within the model folder to the one within the database and displays the list of all different objects.

Important note: This section is not applicable from r2.35.

PostgreSQL specific issues (version 2.35)

Openbravo ERP development using PostgreSQL database is fully enabled. Nevertheless, because of PostgreSQL characteristics, two issues still remain:

1. Openbravo PL/SQL translator translates Oracle PL/SQL format to PostgreSQL format. Unfortunately, this translator is not able to do the reverse procedure of translating PostgreSQL procedures to Oracle PL/SQL format.
2. Openbravo ERP can work with national character sets VARCHAR2 and NVARCHAR2. PostgreSQL database converts these data types to VARCHAR data type so VARCHAR2 and NVARCHAR2 data types would become indistinguishable in the reverse process.

Due to these limitations, in PostgreSQL database environments schema objects can not be exported from the database to database source code inside the database/model folder. Nevertheless, changes in database source code inside the database/model can be easily applied to database schema objects using update.database task.

Summarizing, a PostgreSQL development environment is identical to the Oracle one with the exception of changing the schema objects. This must be done by editing the database source code inside the model folder directly instead of doing it within the database itself. After changes have been made in the database source code in the database folder, update database schema objects by using the update.database ant task.

Development environment ID

There is a set of data called Application Dictionary (AD) data or metadata where Openbravo application components (windows, tabs, processes, etc) are defined. This data is stored and managed in a relational database in the same way that business data (customers, products, invoices, etc) is. Each Application Dictionary record has an unique identifier or ID (primary key columns such as AD_Window_ID, AD_Process_ID and so on). These identifiers are generated using a sequence generator. To be able to share and join Application Dictionary data from different sources, we must guarantee that no collisions happen. The way of doing this is to create a range of IDs for each different source. This range is related to source's development environment ID. The record IDs then range from development environment ID multiplied by 100.000 (one hundred thousand) to development environment ID multiplied by 100.000 plus 99.999. For example, a developer with his or hers ID being 10.027 would get the range of 1.002.700.000 - 1.002.799.999 (dot being the decimal separator).

If the code produced in a development environment is going to be globally shared (as it happens with Openbravo ERP core and modules) it is required to get a global development environment ID from Openbravo. You can do it by registering as an Openbravo Developer. The global development environment ID ranges from 10.000 to 99.999.

For custom code (code specific to a customer deployment) there is no need to get a global development environment ID since that code is not going to be shared and there is no risk of collision. The range from 100 to 999 is restricted to development environment IDs used in working copies for custom code. So there is a limit up to 900 developers working on the same custom code. These values are shared between different custom installations.

The development environment ID is related to a working copy, or more clearly to a developer working on a specific project. If a developer is working simultaneously in more than one project with different code (for example in the trunk and in a branch for a module) he will require a different development environment ID for each working copy. So a developer might have more than one development environment ID assigned to him. Whenever a project is closed - a project branch merged to trunk or a discontinued module branch - the development environment IDs used in that project can be reused for a new one.

Development tasks

Before explaining development tasks in detail, let's summarize steps to be executed during a proper Openbravo ERP development.

1. Check out Openbravo ERP source code.
2. Create the database and build Openbravo ERP source code.
3. Proceed with development by modifying:
   1. Plain files and compiling them.
   2. Database data through Openbravo ERP and exporting them to database source code files.
4. Test that your development works properly.
5. Perform a Head diff to get a report of the changes that have happened in the server from the last time you updated your environment and that you will receive when updating it.
6. Update your source code to the last revision.
7. Import changes in database source code files from the update to your database.
8. Build the system from source code.
9. Test that your development keeps working properly with last revision source code.
10. Perform a Base diff to get a report of the changes you have done and that are ready to be commited.
11. Commit your changes.

Check out

Check out (download) Openbravo ERP source code from Openbravo Subversion repository to your local machine.

Using Eclipse IDE

• Check out is one of the installation steps.

Using command line

• Type inside the folder where you want openbravo project to be downloaded:

svn co https://dev.openbravo.com/svn/openbravo/trunk openbravo

• More information on how to use Subversion checkout command.

Build

First of all, configure Openbravo.properties file.

Using Eclipse IDE

• Import Openbravo ERP projects.
• Define Apache Tomcat server.
• Create the database and build Openbravo ERP.

Using command line

• Create database from *.xml files and build Openbravo ERP in a single step by typing inside your project's folder:

ant install.source

• Or do it component by component by creating first the database...

ant create.database

• ... then compiling the core components of the MVC (Model, View and Controller) framework...

ant core.lib

• ... the Wizard of Application Dictionary (WAD)...

ant wad.lib

• ... the translator...

ant trl.lib

• ... and finally compiling the whole application.

ant compile.complete

• For both single and multiple steps built, deploy openbravo.war file to Apache Tomcat context folder (usually webapps) to access Openbravo ERP via your web browser.

ant deploy

Compile

A whole compilation generates and translates all the windows of Openbravo ERP.

Using Eclipse IDE

• Select Run > External Tools > eclipse.compile.complete Ant task.
• In Console tab, see the evolution of this process. Check that it ends with a BUILD SUCCESSFUL message.

Using command line

• Type inside the folder where you installed Openbravo ERP:

ant compile.complete

Development of Openbravo ERP involves, in many cases, changes in *.html, *.xml, *.java or *.xsql files that need to be processed. Nevertheless, these changes do not require an entire application compilation.

Using Eclipse IDE

• Select Run > External Tools > eclipse.compile Ant task.
• In Console tab, see the evolution of this process. Check that it ends with a BUILD SUCCESSFUL message.

Using command line

• Type inside the folder where you installed Openbravo ERP:

ant compile.development

This partial compilation process allows some parameters both in Eclipse IDE (type them inside the pop up window) and command line (type them following the command):

• To compile only the changes made to any file, add the following parameter:

-Dtab="xx"

• To compile a specific window (e.g., Sales Order window), add the following parameter:

-Dtab="Sales Order"

• Starting from 2.4x version, to compile more than one specific window (e.g., Sales Order, Purchase Order and Goods Receipt windows), add the following parameter:

-Dtab="Sales Order, Purchase Order, Goods Receipt"

• To avoid translation process, add the following parameter to any of the previous parameters:

-Dtr="no"

export.database

If you operate directly your database or do it through Openbravo ERP, you will have to take changes from database and export them to database source code files.

Using Eclipse IDE

• Launch export.database by selecting Run > External Tools > export.database menu item. This task will export both database structure (model) and database metadata (sourcedata).
• In Project Explorer tab, right click on openbravo project and Refresh it.

Using command line

• Type inside the folder where you installed Openbravo ERP:

ant export.database

Head diff

Head diff logs all the modifications of all the files in unified diff format between the head revision of the Subversion repository and your working copy. It shows the differences between the last revision and your working folder and shows the result of mixing the last changes in the Subversion repository and your changes. It is useful to know if your changes are compatible or there are conflicts with the changes of the rest of the team before you update your working folder.

Using Eclipse IDE

• To see the differences of a particular file, right-click on it then select Compare With > Latest from Repository. To compare working copy version of the file with a particular revision, select Compare With > Revision... and type the revision number in the pop-up window.

• A new tab showing the differences between the two versions of the file (if any) displays.

Using command line

• Inside the folder where you installed Openbravo ERP or inside a specific folder, type:

svn diff -r HEAD

• More information on how to use Subversion diff command.

Update

Update your local source code with the last source code revision (version) in Openbravo Subversion repository.

Using Eclipse IDE

• Right click on openbravo project or on a specific folder, then select Team > Update.

• Check update process log by reading Console tab (please notice that some explanations have been taken from SVN on-line book):
  • Files marked with A were added to the working copy since they were included to the repository.
  • Files marked with D were deleted from the working copy since they were excluded from the repository.
  • Files marked with U contained no local changes but were updated with changes from the repository.
  • Files marked with G were merged into the working copy, that is, they cleanly absorbed changes from the repository. In other words, working copy files had local changes but the changes coming from the repository did not overlap local ones.
  • Files marked with C are in a conflicted state in the working copy. This means that the changes from the server overlapped with local changes and you will need to resolve conflicts manually or revert your changes. For every conflicted file, Subversion places three extra unversioned files in your working copy:
    • filename.mine This is your file as it existed in your working copy before you updated it. That is, the file with your latest changes in it.
    • filename.rOLDREV This is the file that was the BASE revision before you updated your working copy. That is, the file that you checked out before you made your latest edits.
    • filename.rNEWREV This is the file that your Subversion client just received from the server when you updated your working copy. That is, the file that corresponds to the HEAD revision of the repository.

Using command line

• Inside the folder where you installed Openbravo ERP or inside a specific folder, type:

svn up

• More information on how to use Subversion update command.

update.database

If you update or edit manually the database source code files, you will have to import these changes to your database.

Using Eclipse IDE

• Launch update.database by selecting Run > External Tools > update.database menu item. This task will update both database structure (model) and database metadata (sourcedata).

Using command line

• Type inside the folder where you installed Openbravo ERP:

ant update.database

Base diff

Base diff logs all the modifications of all the files in unified diff format between the last revision you updated and your working copy. It shows all the changes you did. It is very useful to execute this command before a commit to the Subversion repository because it shows all the changes that you are going to commit in order to review that all files to be commited are right.

Using Eclipse IDE

• To see the differences of a particular file, right-click on it then select Compare With > Base from Working Copy.

• A new tab showing the differences between the two versions of the file (if any) displays.

Using command line

• Inside the folder where you installed Openbravo ERP or inside a specific folder, type:

svn diff

• More information on how to use Subversion diff command.

Commit

Commit your bug fixes or new developments to Openbravo Subversion repository.

Using Eclipse IDE

• Right click on openbravo project or in a particular sub-folder or file, then select Team > Commit.

• A Commit window pops-up where you can select the list of files to commit. You can also add comments to the commit. Click on OK button to go on.

Using command line

• Inside the folder where you installed Openbravo ERP or inside a specific folder, type:

svn commit

• An editor for adding comments will display. Type yours, save it, close the editor and commit will start.
• More information on how to use Subversion commit command.

Revert

In order to resolve any conflicted state, revert any file or directory modified locally to a previous revision of it.

Using Eclipse IDE

• Right click on openbravo project or on a specific folder, then select Team > Revert.

Using command line

• Inside the folder where you installed Openbravo ERP or inside a specific folder, type:

svn revert

• More information on how to use Subversion revert command.

Switch

By switching a folder or a file or group of files, you will be able to bring them to a particular revision number. Let's see an example with database folder.

Using Eclipse IDE

• Right click on database folder then select Team > Switch.... In Switch To pop-up window, check repository URL and fill the desired revision number.

Using command line

• Inside your project's database folder, type:

svn switch -r "revision number" https://dev.openbravo.com/svn/openbravo/trunk/database .

• More information on how to use Subversion switch command.

Merge

When new developments are quite big it is recommended to create a branch for the project development and then merge it back to the main development trunk.

More information on how branching and merging.

compare.database.structure

compare.database.structure task compares database source code files under model (structure) folder and database structure data (tables, views, triggers, procedures and so on) and displays the number of all schema objects. Execute this task before exporting your database to database source code files under model folder or before updating your database from database source code files.

Using command line

• Type inside the folder where you installed Openbravo ERP:

ant compare.database.structure

Openbravo ERP core, Modules and Custom Code

Openbravo ERP is designed to fulfill all customer requirements whatever they are. It is done at different levels each one more specific to the customer than the previous:

• Openbravo ERP core: common functionality without any industry specific detail that is used for most of the customers.
• Modules divided in three different types:
  • Functional modules and Plugins: extended functionality (such a HR module) and specific tools or components (such a connection to a remote banking system). More than one module/plugin could be applied to a customer installation.
  • Localization packs: adaptation of Openbravo Core and modules to a country specific operations (translation and specific rules such as chart of account and taxes).
  • Industry Templates: adaptation of Openbravo Core and related modules to a industry specific operations (for example, a vertical for non-profit organizations). Only one industry template can be applied per customer installation.
• Custom code: customization of Openbravo Core and related modules to completely fulfill customer requirements.

So regardless of the scope of a project - just a small bug fix or a large new functional module - development using ODE can have one of the following objectives:

• contribute to Openbravo ERP core,
• create a pluggable module or
• customize Openbravo ERP to fit some customer requirements.

Customer's production deployment can therefore consist of several elements listed above such as bug fixes, module plugins, new features, etc.

Regardless of the objective, the development process' base is a source code repository updated from different sources. ODE will keep track of the source for each change, but all of them will be managed in the same standard way.

This figure also explains the dependency tree in Openbravo. Openbravo ERP core is completely independent from modules and custom code. A module depends on Openbravo ERP core and other modules it might be based on. Custom code depends on Openbravo ERP core and on all the modules the customer has installed.

Although the development process is almost identical for all of the purposes described above, the custom code development has some specific issues that are explained below.

Contributing your code to Openbravo

You can contribute to Openbravo by participating in the Openbravo ERP core development - from bug fixing to new features - and by creating your own modules that you might later distribute as an extension of Openbravo. Also, these modules might be migrated to Openbravo ERP core at a later stage. Look at Openbravo Contributor's Guide to get a detailed description of the contribution process.

The technical details to configure the development environment (developmentEnvironmentID and range of ids, repository and code line to commit changes, documentation, etc.) are quite similar for Openbravo ERP core and Modules. The next case will try to make these details clear.

Contributors story

Maria joined the Openbravo Community a few months ago. She downloaded and installed the product, got documentation from the wiki and received support from the community through forums. During the evaluation process she found and reported two bugs in the trackers. One of them was fixed one week later. It was urgent for her to solve the other one so she went into the bug, found the cause and fixed it. It was just a small change in a java file.

She wanted to contribute this fix so she registered as a developer. As a result she got a user/password with read access to Openbravo SVN repository and a unique development environment ID that she applied to her development environment. Since the changes she had done were not related to the application dictionary metadata there was no need to change anything in the fix. She packed it and sent it to the Patches tracker. Two weeks later, after reviewing the code, Openbravo team applied it to the trunk with a small correction on the fix that was communicated to her.

She was happy with the experience and contributed three new patches fixing two other bugs and adding a small feature following the same process. After some weeks working like that Openbravo team wrote to thank her for the help and to communicate that her SVN account had been granted a write access to the trunk. Now she was allowed to directly commit to the trunk. After that she continued contributing in a more efficient way, with no delay in applying her fixes to the trunk and getting feedback from the code reviews done at Openbravo.

She had become an Openbravo expert and wanted to do a more ambitious contribution: to greatly enhance the procurement module. So she started by adding a feature request that summarized what she planned to do. Through the feature request tracker she got in contact with Piotr, another senior Openbravo developer who also planned to add some new features to the procurement module. After a short discussion they agreed to work together on this project. They asked for a user/password for the wiki where they opened a project called Procurement enhancement, and wrote down a detailed functional description about what they planned to do.

Gorka, the procurement module responsible at Openbravo, discussed the functional description with them and gave technical guidance for the implementation design. In about three weeks they had a complete documentation for the project. Since the new features were planned to be included in Openbravo ERP core and the resulting design was great, they agreed to include this development in Openbravo ERP core. But they asked the Openbravo SVN administrator for a project branch where Maria, Piotr and Zeng - recently joined to the project - had write access. To isolate the trunk from the changes in the project until it was finished. They updated the project wiki with a link to the project branch to help others browse the code they were developing.

The four project members - Gorka also joined to the project - configured a new working copy in their computers and check out from the project branch. Since Maria was going to work in paralel commiting to the trunk she needed another development environment ID and requested one. Once she received it she had two working copies (Eclipse workspaces) in her computer, one for the trunk and the other one for the project branch. Each one used a separate development environment ID.

The development took around two months. During this time they merged the project branch with the trunk twice to ensure that the changes in the trunk were compatible with their developments. Once they completed all the development they merged again with the trunk and made -in collaboration with Openbravo QA team- a comprehensive testing. A few bugs were found and fixed in the branch. With the OK from QA, they merged the code of the branch with the trunk. Six week later Openbravo launched a new alpha release including this new functionality. From then Openbravo support team took care of the maintenance of that code.

Maria was recognized in the Openbravo community as a smart contributor and was contacted by Giuseppe who planned to develop an HR module. They agreed to work together and followed the same process:

• create a feature request
• create a project wiki
• create a project branch

They discussed their plans with the Openbravo responsible and agreed not to include it in Openbravo ERP core but rather distribute it as as module. So they did not merge back the changes from the branch to the trunk, and that branch is still alive for maintenance. Since the "Procurement enhancement" project was closed Maria reused her development environment ID for that project. The module is distributed as an open source module and has had more than 30.000 downloads in the last three months.

Custom code Management

Custom code development is the last step in the development chain of customer requirements. It could range from barely any changes -because the Industry Template satisfies all the requirements- to a large effort where a number of developers are involved. As mentioned, the development process for custom code consists of the same tasks as development of the core or modules with minor differences.

The figure below explains a full-fledged customer environment recommended by Openbravo. Later in the document, simpler environments are explained. It normally consists of:

• The production environment: Where the customer's Openbravo ERP runs.
• The backup system: There should be a scheduled backup of the production environment to recover the system from eventual disasters.
• The pre-production environment: Where the customer tests of new developments are performed before they are put into production.
• The SVN customer branch: Where all custom code is stored and shared between developers, and from where the pre-production and production environments are updated.
• The development environment: Working copies of the SVN customer branch where developers working on the project implement customer requirements.

Methodology

1. Custom code does not need a particular branch, but one certainly assists with team development. In case you need one, you can request it from Openbravo.
2. Best practices for standardization purposes and avoiding of conflicts should be followed:
   1. Create valid naming rules.
   2. Since custom code is not going to be mixed with other custom code, there is no problem in sharing the same ranges between different custom installations/projects. Define your development environment ID (between 100 and 999) that will generate a specific range of records (for example, a developer with his or hers ID being 102 would get the range of 10.200.000 - 10.299.999).
3. Proceed with the development of the custom code.

Migration from previous releases

There is an easy way to migrate from R2.35MP1 and previous releases to the new way of code management. From a high level perspective, these are the tasks to follow:

1. First upgrade the custom code to the latest version using the upgraders published in Sourceforge by Openbravo.
2. Then prepare a standard development environment:
   • Check out the last stable tag (2.35MP5 at the time of writing)
   • Define your development environment ID depending on your development purpose. Remember that IDs for Openbravo Core and Module contributions range from 10000 to 99999 and for custom code from 100 to 999.
3. Execute the export.database ant task that exports the binary database to the plain XML files inside the database folder. This way, the database source code can now be version controlled.
4. Then move the code from the old system (that has already been updated to R2.35 MP5) to the fresh working copy by copy-pasting it over.
5. Commit the updated working copy to the repository. Note: make sure that any added/new files are also included.

This way, you will now be able to develop your old customer code using the ODE tools and methodology.