Mercurial Manual for Openbravo Developers

Introduction

This manual explains the usage of Mercurial for community developers of Openbravo ERP and Openbravo POS. It details the particular configuration and procedures recommended to work in an Openbravo project.

This is not a complete Mercurial manual. If you are looking for general Mercurial resources, there is excellent documentation:

• The hg help <command> integrated help.
• The Mercurial wiki.
• The hgbook: Mercurial: The Definitive Guide. If you plan to work with Mercurial, reading this is a must.

Terminology

• SCM: Source Code Management. More
• DSCM: Distributed Source Code Management. More
• Repository: A remote copy of a source tree with revision history. More
• Working Copy: Also known as working directory. It's the top-level directory in a repository, in which the plain versions of files are available to read, edit and build. More
• Changeset: It's a collection of all the changes that lead to a new revision of the repository. More
• clone: a complete copy of a repository. More
• pull: a pull propagates changesets from a "remote" repository (the source) into a local repository (the destination). More
• update: it updates the working directory from the repository. More
• commit: commit changes to the given files into the repository. More
• push: to send all differing revisions to another repository. More
• tag: to name a particular revision. More
• branch: a diverging point in time in the revision history. More
• head: repository heads are changesets that don't have child changesets. They are where development generally takes place and are the usual targets for update and merge operations.
• Development branch: a branch of the main repository, usually used to add a new feature to the product.
• Stable branch: a stabilization or maintenance branch of a major release.
• Release stabilization branch: a branch used by Openbravo in Subversion to stabilize an upcoming release and to avoid freezing trunk.
• trunk: name used in Subversion to indicate the branch where the main developer work is done.
• main: name used by Openbravo in Mercurial to describe the repository where the main developer work is done.
• tip: The tip revision (usually just called the tip) is the most recently added changeset in the repository, the most recently changed head.

Introduction to distributed SCMs

Before starting with Mercurial, is a good idea to have a general view of what distributed SCMs are and how they work. First of all, read the Understanding Mercurial and Intro to Distributed Version Control (Illustrated) documents. They illustrate the basic concepts.

In a centralized SCM there is only one central repository. Developers have working copies of this repository, and changes are committed to this central site. It is not possible for developer A to share changes with developer B without passing the changes by the central repository. This problem is solved by the distributed SCMs. Instead of checking out a working copy, you get a full clone copy of the repository.

This means that once you have the repository locally, all the operations are local and therefore very fast. Everyday command like diffs, merges, commits and reverts are all done locally. There's no server to ask for old revisions from a year ago.

Additionally, every cloned repository can be considered as a new branch. Merging is an every day operation in distributed SCMs and it is much faster compared to centralized systems. You merge locally and then optionally push the results to another repository.

Finally, a distributed SCM offers working with different collaboration models, even in a centralized manner.

If you want a quick and nice tutorial, follow the Mercurial Kick Start.

Installation

Use Mercurial 1.1 or later. Use the hg version command to check it.

Debian

If you are are on testing (squeeze) or unstable (sid):

apt-get install mercurial

The current stable version of Debian (Lenny) includes Mercurial 1.0.1, which is old for Openbravo's requirements. If you are running Lenny thenbuild Mercurial from sources

Ubuntu

Install Mercurial

sudo apt-get install mercurial

Gentoo

Install the latest Mercurial release:

echo dev-vcs/mercurial >> /etc/portage/package.keywords
emerge -av mercurial

Mac OSX

There are 2 options:

1. Use the command line version and install it using a prepackaged binary installer. This is the easiest method.
2. Install using MacPorts. This method is a little more involved, because you need to first download and install MacPorts, which involves making sure you have the latest Xcode installed. Once you have MacPorts set up:

sudo port -v install mercurial

Microsoft Windows

There are 2 options:

1. Use the command line version and install it using a prepackaged binary installer.
2. TortoiseHg: an all-inclusive Mercurial binary installer package for Windows, which provides a windows explorer extension (shell extension), so that Mercurial commands can be executed from the context menu of the explorer.

Note: if error SSL: unsupported_protocol is retuned, follow the instructions in point 3.1 in Mercurial SCM Secure Connection

Configuration

You should configure Mercurial just after installing it. On UNIX-like systems, this should be done in your $HOME/.hgrc file. On Windows, these settings can be added to C:\Program Files\Mercurial\Mercurial.ini, or, if you'd like per-user settings, $HOME\.hgrc or $HOME\Mercurial.ini. (if the file does not exist you should create it manually).

Your Mercurial configuration file should have at least the following settings:

[ui]
username = Your Real Name <user@example.com>
merge = your-merge-program

[diff]
git = 1

The username is used to identify the commit author.

It is very important to choose a merge program. There are many popular options to choose from, like Meld, KDiff3 or TortoiseMerge.

The git = 1 diff option specifies to use the extended git format. This allows including file permission changes in the diffs.

You can configure the editor to use for commit messages using the editor option in the [ui] section or by setting the EDITOR environment variable.

Extensions

Extensions allow the creation of new features and using them directly from the main hg command line as if they were built-in commands.

Sample extensions:

• alias: define your own command aliases.
• color: color output for the diff, status and qseries commands.
• fetch: conveniently pull, merge and update in one step.
• graphlog: adds a new command glog that behaves like (a subset of) the normal log command except that it also prints a graph representing the revision history using ASCII characters to the left of the log.
• hgk: allows you browsing the history of a repository in a graphical way.
• histpush: allows you to locally track which revisions of a repository have been pushed to a remote repository.
• rebase: rebase uses repeated merging to graft changesets from one part of history onto another. This can be useful for linearizing local changes relative to a master development tree.
• transplant: allows you to transplant patches from another branch or repository (aka backport).

To enable an extension, add it to the [extensions] section of your $HOME/.hgrc. For example to enable the color, rebase and transplant extensions:

[ui]
username = Your Real Name <user@example.com>
merge = your-merge-program

[extensions]
color =
rebase =
transplant =

Some extensions are shipped along with Mercurial. Others can be added externally. Check the official web page for a list of extensions.

Custom diff program

It is usually be very useful to view a diff using an external program like meld, kdiff3.

Activation of the extension:

[extensions]
extdiff =

Specify the desired program:

[extdiff]
cmd.vdiff = meld

Example of use:

hg vdiff modified_file.java

For more information about extdiff check the official guide.

Topology

From the book Distributed revision control with Mercurial:

"...it's often good practice to keep a 'pristine' copy of a remote repository around, which you can then make temporary clones of to create sandboxes for each task you want to work on. This lets you work on multiple tasks in parallel, each isolated from the others until it's complete and you're ready to integrate it back. Because local clones are so cheap, there's almost no overhead to cloning and destroying repositories whenever you want."

We recommend this process of using cheap local clones. The general process is:

• Have a pristine copy of the remote repository.
• To work on a repository, make a temporary local clone.
• Do as many atomic commits as needed in that temporary clone.
• Once finished, push directly to the master repository (the remote one).

A developer could have several temporary clones of the same repository to isolate different developments. For example, if a developer is fixing two bugs simultaneously but wants the commits and tests to be isolated, he would use two separate clones.

We propose having a topology were $HOME/src contains all the pristine copies of the projects you are working on. And $HOME/workspaces contain the clones of these pristine copies. The repositories from $HOME/src are updated from the central repositories and the ones from $HOME/workspaces are updated from the local $HOME/src repositories.

$HOME/src
  |
  |--- openbravo/
  |-----|
        |--- erp
             |
             |---devel
                 |--- main
                 |--- pi
                 |--- project1
                 |--- project2
             |---stable
                 |--- 2.3x
                 |--- 2.40

$HOME/workspaces
  |
  |--- openbravo/
  |-----|
        |--- erp
             |
             |---devel
                 |--- main
                 |--- pi
                 |--- project1
                 |--- project2
             |---stable
                 |--- 2.3x
                 |--- 2.40

This document will assume that the pristine copies are stored under $HOME/src and the local clones under $HOME/workspaces. If you choose different locations, take it into account when following the examples.

Creating the local pristine clones

While in Subversion a checkout updates your working copy from a repository, in Mercurial you first update your local repository and then the working copy.

In the Mercurial terminology this is called a clone. A clone is a copy of a repository in a new directory. To do a clone:

mkdir -p $HOME/src/openbravo/erp/devel
cd $HOME/src/openbravo/erp/devel
hg clone https://code.openbravo.com/erp/devel/pi

Do as many clones as projects you are going to work on. Remember that these are pristine clones you will keep unmodified.

Keeping the local pristines clones up to date

Check what you're going to pull:

cd $HOME/src/openbravo/erp/devel/pi
hg incoming

To keep your clone up to date, update the repository with these changes:

hg pull

Then, to update your working copy:

hg update

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

hg pull -u

Since this clone is a pristine copy of the remote repository you may want to maintain it up to date with a cron job.

Creating local working clones

To start working on a project, you should create a local clone of the pristine clone:

mkdir -p $HOME/workspaces/openbravo/erp/devel
cd $HOME/workspaces/openbravo/erp/devel
hg clone $HOME/src/openbravo/erp/devel/pi

Periodically you will want to update the local clone from the pristine clone:

cd $HOME/workspaces/openbravo/erp/devel/pi
hg incoming
hg pull -u

These are the clones where you develop your code.

Check in to the central repository

Required configuration

Firstly make sure you have configured your $HOME/.hgrc with your username.

Secondly, to push to the Openbravo repositories you need push access (or someone with push access needs to pull from your repository).

Commit locally

To check if you're really committing what you want to commit:

hg status
hg diff

Note that while Subversion applies the command to the specific directory you are in, Mercurial applies it to the entire tree. To see the status or diff of a specific directory specify it as an argument:

hg status web/js

hg diff web/js/message.js

As the next step, commit your changes to your local repository:

hg commit -m "message"

You can make as many atomic commits as you need. This commits won't be seen in other repositories until you push them.

Push to the central repository

To check what you are going to push:

hg outgoing

To actually send the commits to the central repository:

hg push

If you receive the message "abort: push creates new remote heads", do not do what the message suggests (hg push -f). What this message means is that some changes have been done to the central repository since the last time you updated your local repository. If you do it the server will reject it anyway. We recommend following one of these two approaches:

In case of doubt use the first approach: rebase

Rebase

Check that the rebase extension is enabled in your .hgrc file:

[extensions]
rebase =

Now, type:

hg pull --rebase

This will pull and rebase your local changesets at the same time. More details and options can be found at the Mercurial wiki.

So now you are ready to push your commits:

hg push

In the process of the rebase, it may discover conflicts. In that case it will stop and allow you to fix the conflicts. After fixing the conflicts, use hg resolve to mark the files as resolved, and then, instead of running hg commit just run hg rebase --continue. Example:

$ hg pull --rebase
pulling from /home/johndoe/src/openbravo/erp/devel/pi
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)
merging src/build.xml
warning: conflicts during merge.
merging srv/build.xml failed!
abort: fix unresolved conflicts with hg resolve then run hg rebase --continue

Now we edit src/build.xml and fix the conflicts. Then, we mark the files as resolved:

$ hg resolve -l
U src/build.xml
hg resolve -m src/build.xml
hg resolve -l
R src/build.xml

And we continue the rebase process:

$ hg rebase --continue
saving bundle to /home/johndoe/src/openbravo/erp/devel/pi/.hg/strip-backup/05a5fc850b1f-temp
adding branch
adding changesets
adding manifests
adding file changes
added 2 changesets with 2 changes to 1 files
rebase completed

Merge

Pull the latest changes from the repository:

hg pull

This will create an extra head locally. Merge the two heads:

hg merge

Commit the result:

hg commit -m "Merge heads A and B"

Push to the central repository:

hg push

Fixing a bug

Example: the developer has to fix issue 6265 in main.

The developer starts going to the local work clone of the main repository. Then the developer can start fixing and testing the issue in that clone, doing as many commits as needed. Each commit should be an atomic piece.

cd $HOME/workspaces/openbravo/erp/devel/pi
(edit fixme.java)
hg ci -m "Fixes issue 6265."

When the developer is happy with the fix, the changesets can be pushed to Openbravo repository.

hg push

Before pushing it is a good idea to see what's going to be pushed with hg outgoing

Backporting a bug fix

Example: the developer has to backport the fix of issue 6265 from devel/pi to stable/2.40.

The developer has already fixed the bug in one branch and wants to repeat the fix in another branch. Then he can use transplant to apply the same fix in this branch (4544 is the revision of the commit done to fix this bug in main):

cd $HOME/workspaces/erp/stable/2.40
hg transplant -s $HOME/workspaces/erp/devel/pi 4544

After testing the fix, he can push the update to Openbravo repository and delete the temporary clone:

hg outgoing
hg push

The transplant extension is distributed along with Mercurial. Another possibility to backport changes is to use hg export and hg import.

Developing a new feature

New features can be developed in local repositories. But if other core developers or community members are also contributing to this feature, you want a public repository to share your developments.

Example: the developer wants to start a community project to develop a new feature based on main.

• Create a shared repository based on main.
• Create a local clone as a reference:

hg clone https://code.openbravo.com/erp/devel/modularity $HOME/src/openbravo/erp/devel/modularity

• Create a local working clone:

hg clone $HOME/src/openbravo/erp/devel/modularity $HOME/workspaces/openbravo/erp/devel/modularity

• Edit code, committing in atomic pieces. Push to the shared repository to make the changes available to developers and the community.
• Once the feature is developed, merge the feature branch into main.
• The developer already has local copies of both repositories in $HOME/src/openbravo/erp/devel/pi $HOME/workspaces/openbravo/erp/devel/modularity. So we create a new clone were the merge will be done:

hg clone $HOME/src/erp/devel/pi $HOME/src/erp/devel/merge_modularity

• Then, we pull changes from modularity branch:

cd $HOME/src/erp/devel/merge_modularity
hg pull $HOME/src/erp/devel/modularity
hg merge
(conflict resolution)
hg ci -m "Merged modularity."

Instead of pull+merge+commit, the fetch extension could be used.

Once the merge is done, the changesets can be pushed into the centralized main repository and the merge repository can be deleted:

cd $HOME/src/erp/devel/merge_modularity
hg outgoing
hg push https://code.openbravo.com/erp/devel/pi
rm -rf $HOME/src/erp/devel/merge_modularity

Finally, the modularity repository can be deleted.

Backing out changes

Generally if you make a mistake and want to fix it, you should just edit sources to fix it and commit a new revision. This preserves history of the mistake and its correction and is suitable for routine programming errors.

I've committed one changeset locally, it's not pushed

If you commit something that you really cannot tolerate being in history (e.g. legally forbidden files, passwords) it is possible to discard the commit only if you have not yet pushed it (Once it is on the server, it is permanent). If you have just committed the change and nothing else, just run hg rollback. Your working copy will still be modified; you can hg revert if you need to.

Alternatively you can also make a version of the repository that does not include the latest changes. Use hg clone -r and pass in the "last known good" changeset ID.

I've committed one changeset locally, it's pushed

Just back it out and push it:

hg backout -r REV
hg push

I've committed more than one changeset locally, it's not pushed

If you commit several changesets locally but you haven't pushed them, it is possible to backout the changes in 2 different ways:

• Preserving history: run "hg rever -a -r REV", so that REV is the revision you want to have as the new tip of the repository. Then commit change changes and push them.
• Modifying the local history: in case you absolutely do not want the commits to go to the central repository, it is still possible to kill off bad changesets. The simplest way of doing this is to use the hg strip command, added by the MQ extension:

[extensions]
mq =

If you strip out a changeset from your local repository, it will be removed along with all descendant changesets. Be careful. (Do backups)

Alternatively you can also make a version of the repository that does not include the latest changes. Use hg clone -r and pass in the "last known good" changeset ID.

I've committed more than one changeset locally and it's pushed

The easiest way is to revert your local working directory to the REV you want to revert to and then commit the changes:

hg revert -a -r REV
hg commit -m "Back our changesets A, B and C"

Triggering actions in the issue tracker

As a general rule your commit must be related to an issue reported in Mantis. You can benefit from the integration between Mercurial and Mantis. Depending on the comment you write for the commit, a note can be automatically added to the issue. Moreover, the status of the issue can be automatically set to resolved.

• Adding a note: To add the commit comment as a note of the issue, you should add to the comment one of the words bug or issue (case insensitive) followed by the number of the issue. In the middle you can put none or more spaces. For example, the following messages would add a note to the issue:
  • Issue 107.
  • Related to the problem in bug107.
• Solving an issue: To mark the issue as resolved, you should add one of the words fixed or fixes before the text needed to add a note. If we wanted to resolve the issues, the previous examples could be:
  • This patch fixes issue 107.
  • Solves the login problem. Fixes bug 107.

Take into account that writing issue A and issue B in the same commit message will add comments to both issues. So, for example, solve issue 321, related to issue 223 would add a comment to issues 321 and 223 and solve issue 321. If you want to reference another issue in the same comment, use issue #B instead. In our example: solve issue 321, related to issue #223.

New repository for new feature

Sharing changes with other developers is an easy task with SSH or using the built-in web server. However, there are situations where developers want to share the work with other developers or with the community in a centralized manner.

For those situations, you can ask for a new repository, by email request to staff.rm@openbravo.com. Please, follow this template:

We need a new repository:
- New repository: https://code.openbravo.com/<subpath>/<repository name>
- Description: 
- Contact (team): 
- Read permissions: 
- Write permissions: 
- Copy of: none or https://code.openbravo.com/<some existing repo>
  - Revision:

e.g:

We need a new repository:
- New repository: https://code.openbravo.com/erp/pmods-branches/org.openbravo.retail.ournewrepo
- Description: Our new repo
- Contact (team): Platform Team <team.platform@openbravo.com>
- Read permissions: Platform Team, Retail Team
- Write permissions: Platform Team
- Copy of: https://code.openbravo.com/erp/pmods/org.openbravo.retail.sessions
  - Revision: tip

Remote creation

This feature is not implemented yet in code.openbravo.com

There is no built-in support in Mercurial for server-side copy of a branch (i.e. remote to remote cloning). However, an interactive script could be added to the server to provide this feature. An example session could look like this:

$ ssh $USERNAME@code.openbravo.com 'create erp feature-1'
Clone another ERP branch? Answering no will create an empty repository [Y/N]: Y
Name of the branch to clone: erp/devel/pi
...
Your new branch is at http://code.openbravo.com/erp/devel/feature-1

Core developers are allowed to create remote clones of the main repository.

An alternative to SSH is to create your own web interface to manage these requests.

New developer & access controls

This feature is not implemented yet in code.openbravo.com

Every repository will have one or more developers in charge of them (manager). The Project Managers decide who can pull/push and who cannot.

To add a new developer, an interactive script could be added to the server to provide this feature. An example session could look like this:

$ ssh $USERNAME@code.openbravo.com 'addhguser'
Create a new account? [Y/N]: Y
Developer user name: johndoe
Developer e-mail: john@doe.com
...
New user created. An e-mail has been sent to john@doe.com with the developer credentials.

Equally, to delete a developer account:

$ ssh $USERNAME@code.openbravo.com 'delhguser'
Delete an existing account? [Y/N]: Y
Developer user name: johndoe
This is permanent. Are you absolutely sure? [Y/N]: Y
...
User johndoe deleted.

Finally, the developer in charge of a repository is capable of managing the access controls. An example session could look like this:

$ ssh $USERNAME@code.openbravo.com 'hgacl'
Manage access controls? [Y/N]: Y
You are the manager of the following repositories:
  * erp/devel/pi
  * erp/devel/localization
  * erp/devel/my-feature-1
Select a repository: erp/devel/my-feature-1
Developer user name (use 'all' for anonymous): johndoe
Current permissions of johndoe in erp/devel/my-feature-1:
 +pull
 -push
Select action: +pull
...
Permissions modified for user johndoe in erp/devel/my-feature-1:
 +pull
 +push

Sharing repositories with local developers

The easiest way to share a repository with a developer in the same LAN is to use hg serve, it includes a mini-web server:

~/workspaces/openbravo/erp/devel/pi $ hg serve -v
listening at http://192.168.102.123:8000 (bound to *:8000)

Alternatively you can clone/push/pull directly using SSH:

hg clone ssh://john@192.168.102.123/workspaces/erp/devel/pi

In this case the repo would be located in /home/john/workspaces/erp/devel/pi. To specify absolute paths use double slashes (//):

hg clone ssh://john@192.168.102.123//home/john/workspaces/erp/devel/pi

Write meaningful commit messages

Both the hg log command and the hgweb web interface print only the first line of a commit message by default. So it's best to write a commit message whose first line stands alone. Our recommendation is to write short but informative messages that tells us something we can't quickly figure out from the diff.

Template for good commit messages

Short (72 chars or less) summary of changes.

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so. Leave a blank line between the summary and the
detailed explanation.

If needed, further paragraphs can come after:

  - Bullet points are fine.
  - Second bullet point.

Example of a good commit message

Fixed issue 27183: make postcreate and postupdate stop on build errors

This ensures that importing masterdata and sampledata will not
fail because of this past error.

Example of a bad commit message

Fix issue 27183: make the postcreate and postupdate ant tasks stop the build process when errors are found. This is useful to ensure that importing masterdata and sampledata will not fail later on in the process. So changed the "onerror" paramater accordingly. Now that I'm writing, I'd also like to say hello to my friend John Doe.

Changing push password

To change your password to push to code.openbravo.com, use the hgpasswd utility.

Mercurial for Subversion refugees

Subversion	Mercurial
svn co URL	hg clone URL hg update
svn diff	hg diff
svn status	hg status
svn add file1 file2	hg add file1 file2
svn del file1 file2	hg del file1 file2
svn commit -m "message"	hg commit -m "message" hg push
svn update	hg pull -u / hg pull --rebase
svn log	hg log
svn log --limit 5	hg log --limit 5
svn diff -c 6445	hg log -r 6455 -p
svn info	hg identify hg paths
svn revert file1 file2	hg revert file1 file2
svn revert -R .	hg revert -a

Mailing list

There is mailing list called openbravo-commits. For every push to the Openbravo ERP repository an e-mail is generated and sent to the list showing all the changesets of that push, their authors, dates and diffs.

Mirrors

There is one read only mirror in SourceForge:

• Mercurial mirror

FAQ

How can I store my push/pull login and password?

You can specify the credentials globally in your main hgrc file. As an example, edit $HOME/.hgrc ($HOME\mercurial.ini in Windows) and add the following section:

[auth]
ob.prefix = code.openbravo.com
ob.username = myusername
ob.password = mypassword

For more information about this check the hgrc(5) man page.

If you are using an old Mercurial (previous to 1.3), you can save it per repository. Editing <hg-clone>/.hg/hgrc of the repository and edit the URL:

https://user:password@code.openbravo.com/project/stage/repo

I'm running hg push -f and it fails! What do I do?

Running this command is forbidden. In fact it intentionally fails with an error similar to:

transaction abort!
rollback completed
abort: pretxncchangegroup.forbid_2heads hook exited with status 1

To fix this situation follow these steps.

How do I add a file to the ignore list, to prevent it from being committed?

If its of general interest edit the <hg-clone>/.hgignore file and add your list of files there. Take into account this file is version controlled as a common file and that it has to be committed. For example to ignore config/Openbravo.properties:

echo config/Openbravo.properties >> .hgignore
hg ci -m "Ignore config/Openbravo.properties"
hg push

This is the equivalent to the svn:ignore property in Subversion.

How do ignore files *only* in my local repository?

You may want do ignore files locally, without having to modify the general .hgignore file. To achieve this, edit <hg-clone>/.hg/hgrc and add:

[ui]
ignore = /absolute/path/to/repo/.hg/hgignore

And use /absolute/path/to/repo/.hg/hgignore as the local ignore file.

How do I go to revision XY in my working directory?

Use hg update to achieve this. For example to go to revision 2345

hg up -C 2345

How do I create a new repository for testing?

mkdir my-new-repo
cd my-new-repo
hg init
(add some files)
hg addremove
hg commit -m 'Initial commit'

Can I edit the last commit message?

Yes you can, as long as it's not pushed. First, enable the mq extension in your $HOME/.hgrc file. Then:

hg qimport -r tip
hg qrefresh -m "Enter here the new message"
hg qfinish -a

Documentation

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.