Talk:ADempiere Version Control

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.

Release 380 Development and Earlier

This was what was done with mercurial and source forge.

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.

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.
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.
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 the working repository.

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
git clone git:// org.adempiere.webservice

In the mercurial working create or edit the file .hgsub and add the following lines


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

hg update --verbose --rev tip -C
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
git clean -f

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.

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

From My MacBook by Redhuan D. Oon

Tony, i believe it has something to do with my MacBook and Eclipse version. They don't always jive with stuff out there so you must be right on that version advice.Redhuan D. Oon 03:12, 7 July 2010 (UTC)
  • You may not find the .hgrc file in your <home-dir> so you just create it there with pico utility. If your Eclipse opens with issue in Mercurial, at your terminal box run: hg debuginstall to see what can be wrong.
  • In Eclipse, you need to set the Hg command to your disk location such as in my case it is /usr/local/bin/hg
  • Follow the terminal command to clone but do it as root or else it seems to deny you permission.
    • Below is my first clone statement which is same as advised in article:
hg clone -U adempiere

Creating local working clones

  • After the above i can then do this in my Eclipse by:
    • Right-click on my left panel and select Team and Import.
    • Choosing Mercurial option
    • Then telling the dialog where my local clone and where is my workspace as shown in image here.
    • Then click Finish and it takes not long to show up in your Eclipse IDE. As seen in the image below, its folder structure appears to arrange exactly as expected even though its harddisk layout was so different during cloning. This must mean that the Mercurial app is working.

Keeping up to date

  • Now, as usual, right-click on the Project
  • Select Team and see the pop right selection box as shown below.
  • Note the new options for Push, Pull besides the usual "Commit" and "Update" selection.
  • I suspect these words have improved my sex life a lot. There is now more foreplay instead of committing right away. Try it.

Pointing to Heng Sin's Kenai Project

  • Low Heng Sin announced his own Mercurial branch in a Kenai repository here.
  • In order to fetch his work, i created a new folder as /opt/repos/kenai and execute the command:

hg clone -U

  • When the downloading process finishes (which is dependent on your download speed), you can then launch your Eclipse and Import via Mercurial Clone process.
  • This time set the Repository Location URL as opt/repos/kenai/hengsin-development
  • Set your Clone Destination (workspace)
  • Check the box for Search for .project files in clone and use them to create projects
    • This is important for the plugins to show up in each other's MANIFEST.
  • Start the project creation by clicking on Finish.

Spring DM Environment

(This is deprecated. See note 2 para further below)

  • As Heng Sin's project is setup as OSGI plugins under the Spring DM environment, you still have one more thing to install in your Eclipse.
  • Following advice from SpringSource you can install via Eclipse by pointing to a new update site

My Notes

  • In my Eclipse i set the Preferences > Plug-in Development > Target Platform > Target definitions: Running Platform (Active) or else there be eclipse plugins unresolved errors
    • INVALID - Set to the given Equinox-Target in HengSin-Development.
  • I use latest Helios Eclipse and update with Mercurial and Spring DM (minimal options)
    • INVALID - Spring DM not needed in Eclipse as the Kenai project already has them.

To Update Further

  • To update further after the clone above you just su root and in the hengsin-development directory issue this command:
hg pull

The following prompts will appear:

searching for changes
adding changesets
adding manifests
adding file changes

Progress Errors (solved, see below)

Finally got it all without errors
  • At the moment i got cyclic complaints in my IDE, (solved by forcing Manifest compile)
  • A gemini.web.tomcat and javax.ejb plugin resources missing,
  • tomcatConfig has missing 'src' (create a 'src')

Progress Notes

  • Aha! Finally solved! Now you can ignore all the above. It is definitely solved by:
    • Setting the workspace to workspace/hengsin-development so that the Equinox-Target synchs its ${workspace_loc} variable, as shown here.
  • When i test launched the Swing client i noticed the version is showing 360LTS. This answered my dummy question which HengSin did not answered. This is how the guru teaches - by leaving my ass alone.
  • In the OSGI Framework - adempiere.equinox.swing configuration, Arguments tab, VM arguments, replace Hengsin's with your own i.e.:
  • During launch, the splash screen got the properties values but seems to hang and error message:
Invalid base directory: /Adempiere
(in progress) - Redhuan D. Oon 04:27, 27 August 2010 (UTC)
  • Then i added another argument:
and no more such complaint but it still seems to hang there. Console display below:
osgi> 2010-08-27 12:38:21.156 java[34670:10b] [Java CocoaComponent compatibility mode]: Enabled
2010-08-27 12:38:21.157 java[34670:10b] [Java CocoaComponent compatibility mode]:   Setting timeout for SWT to 0.100000
Started service locator: org.adempiere.base.equinox.EquinoxServiceLocator@79bff971
2010-08-27 12:38:21.625 java[34670:27f03] *** -[NSConditionLock unlock]: lock  (<NSConditionLock: 0x123b01120> '(null)') unlocked when not locked
2010-08-27 12:38:21.625 java[34670:27f03] *** Break on _NSLockError() to debug.

SourceCode Hung

  • The above issue is at startClass.newInstance(); (org.compiere.apps.AMenu) .
  • So i tried something else such as RUN_setup and got stuck too. Debugging progress here. (Actually the cause is that MacBook starts X not on first thread. Solve by removing -ws from arguments.)

SourceCode UnHung

  • Mysteriously the above hung scenario has resolved. Perhaps after it detected the new jars after the build. Remember HengSin talked about the refactoring of Env to AEnv and that things might be broken, so after the build.xml must have kicked the right context around.
    • But it could also be this other thing i did today, which is to switch the Mac Java from 1.6.0 to Java6
  • However when i press the Server connection icon, i can only get Oracle selection and not PostgreSQL. Ah well, more scuba diving.. - Redhuan D. Oon 08:48, 30 August 2010 (UTC)
    • Solved!, and i learnt sumtin interesting :)
    • HengSin updated this and i pull from his changes to my clone by using Terminal going to /opt/repos/kenai/hengsin-development and execute hg pull. Then in my Eclipse i select Project/Team/Pull (this may be redundant if i setup more properly in my Eclipse.)

ImportAdempiere Issue

  • Now i get psql: FATAL: no pg_hba.conf entry for host "fe80::21c:42ff:fe00:0%en3", user "adempiere", database "adempiere", SSL off
  • Done all sorts of things to my /Library/PostgreSQL/8.3/data/pg_hba.conf, still trying.
  • Solved due to my RUN_setup using PC name instead of 'localhost' for HOST or SERVER.
    • Many thanks to RhodiumToad of chatroom.

Visit Kenai forum

  • If there are no issues and I got some further happenings I will report here.

Reading Materials

See Also