ADempiere Version Control
From ADempiere ERP Wiki
Install the Version Control Software
Install Mercurial and Clients
- Find the mercurial software at: http://mercurial.selenic.com/downloads/. 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
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 http://git-scm.com/download.
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.
- 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 http://hg.code.sf.net/p/adempiere/code adempiere-code
- Enter this on the command line or use it in your tool of choice to create the pristine clone.
Don't forget to add the -U option! E.G. hg clone -U http://hg.code.sf.net/p/adempiere/code 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.
Keeping the local pristine clones up to date
To keep the pristine clones up to date, simply pull the changes from the remote repository:
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://github.com/adempiere/extension_libero_hr_and_payroll.git org.eevolution.hr_and_payroll git clone git://github.com/adempiere/extension_libero_manufacturing.git org.eevolution.manufacturing git clone git://github.com/adempiere/extension_libero_warehouse_management.git org.eevolution.warehouse
In the working clone, update the mercurial repo with the following command:
hg update --verbose --rev tip -C
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:
To keep your clone up-to-date, add these incoming changes to the repository:
When you pull changes into your local clone, this just updates the repository, not the 'working copy'. To update your 'working copy':
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.
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: http://www.selenic.com/mercurial/wiki/index.cgi/QuickReferenceCardsAndCheatSheets * The Mercurial FAQ. * HgMigrationDocs from NetBeans Wiki. * Mercurial Manual for Openbravo Developers