ADempiere Version Control

From ADempiere ERP Wiki

(Redirected from Mercurial Test Environment)
Jump to: navigation, search

Table_of_Contents#Developer.27s_Guide | ADempiere Version Control | Create your ADempiere development environment


Install the Version Control Software

Install Mercurial and Clients

  • Find the mercurial software at: Version 2.9 or higher is recommended. Some excellent GUI tools exist such as TortoiseHG - just be sure to use the most recent version.
  • Follow the configuration instructions for your chosen tool - specifically to set the user name. We follow the convention Full Name <e-mail>.
  • A number of plug-ins exist for Eclipse as well.

Install the HG Flow extension

This extension helps follow our Software Development Procedure. The extension is available at

Install Git

ADempiere has a few repositories for contributions that use git as the version control. Mercurial will set these up as sub-repositories and you will need git to clone this code. Git can be downloaded at

Cloning SourceForge Repositories

Once you have the software installed and are comfortable using the basic commands, you can setup your working repositories on your local development environment and clone (basically copy) the SourceForge repositories. The best-practice way of doing this is to maintain two local repositories: a pristine clone of the SourceForge repository and a working copy of the pristine clone.

Creating the Local Pristine Clones

A clone is simply a copy of a repository in a new directory and is created by the following command: hg clone <source> <destination>

A 'pristine' clone normally refers to a clone which is created from a remote repository and is only used to create further local clones. No development is done in the 'pristine' clone so it only contains the revision history but no actual code. The pristine clones basically serve as a mirror of the sourceforge repositories.

Image:Note.gif Note:

By default the clone command performs an update (check-out) of the repositories tipmost head of the default branch. When creating a pristine clone, use the mercurial -U or --noupdate option, which means no 'working copy' is checked out in the cloning process.

  • First create a directory for your cloned SourceForge repositories:
    • For example: /opt/repos/sourceforge
  • Change to this directory:
    • E.g.: cd /opt/repos/sourceforge
  • To make a clone of the an ADempiere repository, visit the SourceForge site and click on the repository you want to clone. Copy the read only (RO) access code that appears on the repository page. It should look something like this
hg clone adempiere-code
  • Enter this on the command line or use it in your tool of choice to create the pristine clone.
Image:Note.gif Note:

Don't forget to add the -U option! E.G. hg clone -U adempiere-code

  • There is a lot of history so the cloning process for the main repository (Code) takes a significant amount of time. (The full clone directory size is over 2 GB.) Thankfully, you only have to do this once.
  • Clone any additional pristine repositories you require.
Image:Note.gif Note:

If you just want to clone a single branch of a repository, say the Libero branch of the eevolution repository, you can add the branch name to the end of the url as #name. E.G. hg clone -U libero

Keeping the local pristine clones up to date

To keep the pristine clones up to date, simply pull the changes from the remote repository:

hg pull

As we don't need a 'working copy' in our pristine clones, there is no need to do a 'hg update' here.

Local working clones

Creating local working clones

  • To start working on a project, you should create a local clone of the pristine clone. First create a directory for your local working clones:
    • For example: /opt/repos/workspace
cd /opt/repos/workspace
hg clone -U /opt/repos/sourceforge/adempiere-code adempiere

These are the clones where you develop your code.

Working with the git Subrepositories

Once git is installed, the sub repositories have to be added to each repository (working and pristine). Do this by running the following commands in each repository.

git clone git:// org.eevolution.hr_and_payroll
git clone git:// org.eevolution.manufacturing
git clone git:// org.eevolution.warehouse

In the working clone, update the mercurial repo with the following command:

hg update --verbose --rev tip -C
Image:Note.gif Note:

If the target directories already exist, delete them, clone the git repositories and then use mercurial to update to the desired revision.

If you get errors related to the git repositories, try to repeat the above or clean up the git repositories with the following commands and try again.

git fetch
git reset --hard origin/master

Keeping up to date

Periodically you will want to get the latest changes from SourceForge into the pristine clone and update the local clone from the pristine clone. You can do this using the tools, like TortoiseHG, or by the command line. The basics are the same.

Open/enter the repository you want to get up-to-date. (E.G. cd /opt/repos/sourceforge/adempiere-code)

First, and optionally, check what you're going to pull. If this command returns nothing, the repository is up-to-date:

hg incoming

To keep your clone up-to-date, add these incoming changes to the repository:

hg pull

When you pull changes into your local clone, this just updates the repository, not the 'working copy'. To update your 'working copy':

hg update

Note that it is possible to combine these two steps in one:

hg pull -u

The full process to get the latest code into your working repository would look like this:

cd /opt/repos/sourceforge/adempiere-code
hg incoming
hg pull
cd /opt/repos/workspace/adempiere-code
hg incoming
hg pull
hg update

Pushing your changes to the Source Forge repository

To publish/push changes to Source Forge, you will need to have read/write access to the project and one of the project admins can grant this permission to you once you ask for it. To publish your changes, follow the instructions on the Source Forge site.

Image:Note.gif Note:

Here you need to be careful. A change pushed to SourceForge will be pulled into thousands of local repositories around the world. It is not something that can be easily undone so make sure you follow the Software Development Procedure. If you are concerned at all - make a contribution repository on SourceForge and push your changes there. Ask for help in the forums.

It goes without saying but test your code before you push. Occasionally, you will need to share broken code with a larger team as a work in progress but try to avoid this.

Work in branches and make sure you commit and push to a specific branch. The Software Development Procedure describes how to set these up.

First commit your changes to the working repository. Use good comments to identify the change and what is important about it. Reference bug trackers or forum posts that provide more context. If working in a feature branch, preface the comment with the feature tag: e.g. ADEMPIERE-123.

Before you push changes to the pristine repository, pull the most recent changes from SourceForge to your pristine clone and from the pristine clone to your working clone and deal with any merging issues.

When you are ready to push, push from the working copy to your local pristine clone and check that you pushed what was expected. If necessary, roll-back the push, fix the problems and try again.

When everything is correct, push from your pristine clone to the SourceForge repository.


For more information about Mercurial:

   * The Mercurial wiki.
   * The hgbook: Mercurial: The Definitive Guide.
   * Cheat sheets:
   * The Mercurial FAQ.
   * HgMigrationDocs from NetBeans Wiki. 
   * Mercurial Manual for Openbravo Developers

See Also

Personal tools