This page contain obsolete information, iDempiere has moved to maven and git

The iDempiere developers all use shared repositories (mostly on Bitbucket). We mix them, we create our own code, we let others review it, throw it away and for all these work we can use Mercurial. On this page I will collect some best practices I found while working in this project.

Rules for the Repository of the Swing Maintenance Team (SMT)

The Repository is owned by one person (Thomas Bayen) so it is assured that commits are worked on one after the other. Thomas is responsible to synchronize the repository with the main trunk from time to time.

If you have an enhancement you first create a JIRA tracker. Then you commit to your own cloned repository using the tracker ID and the tracker title as the commit message. Every new issue has to be based on the actual main trunk version (branch "development" - whatever means "actual" for you: you may have synchronized with main trunk further than the swing repo if you want) - not on the swing branch. (Only if you stick to this rule we can assure that every issue commits are independent from other issues!). So you open a new head in branch "development" for every issue. (It may be you have to use the "-f" switch of hg for that.) Then you do a pull request to the swing repository.

I will integrate all issues as new heads into the swing repository. We can pick them one by one if they are reviewed and discuss them separately with the trunk maintainers.

If you add something to an issue you add to the head for that issue and choose the same commit message.

If your issue depends on another issue you may take the head of this parent issue as your commit base and use a commit message of your new issue tracker.

At last I created a branch "swing". In this branch I merge all heads of "development". This is our "stage" for testing and peer review purposes. I would invite everyone to use that version. (I use it in daily work so I will keep it as stable as possible.)

And yes - juggling with commits and heads confuses your mind highly. Don't think it's not the same for me. :-) If you see something that can be improved or made easier on the BBP please tell me.

Links

I still am looking for the best way to manage our repositories and experimenting with them. For that I collect some links here:

Mercurial Tip and Tricks

using a format template for commit output

I don't like the multi-line commit log format of Mercurial.

 $ hg log -l 1
 changeset:   8465:b448296a1f9a
 branch:      development
 tag:         tip
 parent:      8464:26b3256a4fbb
 parent:      8460:4ce4169df8fc
 user:        tbayen
 date:        Tue Feb 12 13:09:46 2013 +0100
 summary:     merge swing head

You can do better with a line like this that gives you one line per commit:

 $ hg log --template='{rev}:{node|short} {branch}\t{date|shortdate} {author|short} \t{desc|firstline}\n' -l 3
 8465:b448296a1f9a development	2013-02-12 tbayen          merge swing head
 8464:26b3256a4fbb development	2013-02-12 tbayen          backout ce681a208126
 8463:d96a0249c3a5 development	2013-02-11 Nicolas Mico    Merged tbayen/idempiere-swing into development

You can even do better if you write the following line into the file /etc/mercurial/tbayen-style

 changeset="{rev}:{node|short} {branch}\t{date|shortdate} {author|short} \t{desc|firstline}\n"

and then use

 hg log --style=/etc/mercurial/tbayen-style -l 3
 8465:b448296a1f9a development	2013-02-12 tbayen          merge swing head
 8464:26b3256a4fbb development	2013-02-12 tbayen          backout ce681a208126
 8463:d96a0249c3a5 development	2013-02-11 Nicolas Mico    Merged tbayen/idempiere-swing into development

And you can even do more better if you write the following into the file ~./.hgrc

 [ui]
 style=/etc/mercurial/tbayen-style
 username=tbayen

Now you can write

 $ hg log -l 3
 8465:b448296a1f9a development	2013-02-12 tbayen          merge swing head
 8464:26b3256a4fbb development	2013-02-12 tbayen          backout ce681a208126
 8463:d96a0249c3a5 development	2013-02-11 Nicolas Mico    Merged tbayen/idempiere-swing into development

If you ever feel that you need the standard layout you can use

 $ hg log --style=default -l 3

Mercurial Command list

These are the mercurial commands I use in daily work:

cloning repository

hg clone ssh://hg@bitbucket.org/tbayen/idempiere-swing

My first step to create a new copy of the main repository. If you want to work seriously with the project you should first create your own account on Bitbucket and clone the main Repository there. Then you can clone your working system with the given command from your Bitbucket Repository. So you can later easy upload your commits and show them.

If you ask what is the main repository... This is an open project and you can choose whatever branch you want and whoever you trust. Said that I prefer Carlos Ruiz Branch. If you want to take part in the Swing Development you can use my SMT branch

removing a not adopted commit

Example: nmicoud made a commit, pushed it to his Bitbucket Repository and eventually made a pull request to the master repository (tbayen/idempiere-swing in the example). But the master did not accept the code and solved the problem (after some discussion on jira or such) slightly different. Now it is probably that you have a merge conflict between both repos. You can not even synchronize your repo with the "sync" button on the Bitbucket overview page. Even if there is no merge conflict you should not just merge but you have to decide which of the both commits you want to use.

You can't solve that on the Bitbucket web interface, you have to do it in your home repo:

 hg pull ssh://hg@bitbucket.org/nmicoud/idempiere-swing-nm
 hg pull ssh://hg@bitbucket.org/tbayen/idempiere-swing

Now you have all kinds of changes in your repo. You could just use the branch from the main repo with "hg update -C swing" and feel lucky (However this will leave an unclosed head) or you may want to correct your private working branch to let the merge work.

collecting informations about the state of the repository

Perhaps you want to do know more about what happens. You can use TortoiseHG do get a graphical view of your branches. But the commandline is also useful. Let us collect some informations:

 $ hg heads
 8463:d96a0249c3a5 development	2013-02-11 Nicolas Mico 	Merged tbayen/idempiere-swing into development
 8460:4ce4169df8fc swing	2013-02-11 tbayen 	merge fec3d762a863
 8457:fec3d762a863 development	2013-02-11 nmicoud 	IDEMPIERE-622 Improvement on locations

We have three heads. The first seems to be the running branch of nmicoud. I call this his "private" branch. The second is the "swing" branch from the SMT repository. The third is a actual commit from SMT branch that is not yet accepted from Carlos Trunk (as such by the above BBP rules for the SMT branch).

 hg parent
 8463:d96a0249c3a5 development	2013-02-11 Nicolas Mico 	Merged tbayen/idempiere-swing into development

The active head is the first from the above. This is nmicouds working branch.

 $ hg log -r "ancestor(d96a0249c3a5, 4ce4169df8fc)"
 8452:3b92d1d047fe development	2013-02-08 globalqss 	IDEMPIERE-621 Postgresql altercolumn not able to alter some tables

This is where nmicoud's head last synchronized with the main trunk.

 $ hg log -r "ancestor(., swing)"
 8452:3b92d1d047fe development	2013-02-08 globalqss 	IDEMPIERE-621 Postgresql altercolumn not able to alter some tables

This is an easier and more readable way to express the same.

You should know that there is another - a "hidden" head. It may be concealed by further work. I speak of the head with the last actual commit from Carlos Ruiz' main trunk. The following command may help:

 $ hg log -r "ancestor(swing, development)"
 8452:3b92d1d047fe development	2013-02-08 globalqss 	IDEMPIERE-621 Postgresql altercolumn not able to alter some tables

I do not trust this full because there are more than one "developer" head in the repository. We should test this logic and perhaps someone knows a better way. Up to now I always check this back with TortoiseHG.

No we have to decide what to do.

Solution 1: Closing private branch and work from main development head

We can close our private branch and begin new development on the official trunk:

 hg commit --close-branch -m 'closing head'
 hg update -C 3b92d1d047fe

You can also work on at the swing peer review branch:

 hg update -C swing

Solution 2: Identifying the problematic commit

If we have other worthful work in our private head we can even undo the "wrong" commit and merge with the main tip. First we have to identify the problematic commit. If you do not know it you can let hg help to find it and answer some of our questions:

Which new commits are in our private head?

 $ hg update swing; hg merge -P tip
 3 Dateien aktualisiert, 0 Dateien zusammengeführt, 0 Dateien entfernt, 0 Dateien ungelöst
 8428:09ba2881b4ce development	2013-02-03 tbayen 	IDEMPIERE-604 Error if window has more than 1000 rows
 8430:4a2d6f175f51 development	2013-02-06 tbayen 	merge 09ba2881b4ce IDEMPIERE-604
 8431:bd7a0cab02fe development	2013-02-06 tbayen 	merge 001720f1f2b7 IDEMPIERE-607
 8456:ac84e6dde2b9 development	2013-02-10 tbayen 	merge 47a440af72dd
 8462:ce681a208126 development	2013-02-08 nmicoud 	Improvement for locations
 8463:d96a0249c3a5 development	2013-02-11 Nicolas Mico 	Merged tbayen/idempiere-swing into development

Which new commits are in the swing head?

 $ hg update tip; hg merge -P swing
 0 Dateien aktualisiert, 0 Dateien zusammengeführt, 0 Dateien entfernt, 0 Dateien ungelöst
 8457:fec3d762a863 development	2013-02-11 nmicoud 	IDEMPIERE-622 Improvement on locations
 8458:3289e3ef8414 swing	2013-02-11 tbayen 	created branch swing for testing version of the swing maintenance team
 8459:c6e3667b5868 swing	2013-02-11 tbayen 	merge 47a440af72dd
 8460:4ce4169df8fc swing	2013-02-11 tbayen 	merge fec3d762a863

Which files are affected by the merge conflict? (This dicards your local changes. Be sure to commit before if you have not yet.)

 $ ( hg update tip -C; hg --config ui.merge=internal:fail merge swing; hg resolve --list; hg update tip -C ) | grep -E '^U'
 U org.adempiere.ui.swing/src/org/compiere/grid/ed/VLocation.java

In which commits is this file changed?

 $ hg update swing; hg log -f org.adempiere.ui.swing/src/org/compiere/grid/ed/VLocation.java -l 3
 3 Dateien aktualisiert, 0 Dateien zusammengeführt, 0 Dateien entfernt, 0 Dateien ungelöst
 8457:fec3d762a863 development	2013-02-11 nmicoud 	IDEMPIERE-622 Improvement on locations
 8141:7f170d6a43f8 development	2012-12-13 richard1988 	IDEMPIERE-455 Discover and fix FindBugs problems / Eclipse warning -> not used
 7636:c31311312ffb development	2012-09-12 globalqss 	IDEMPIERE-417 Update BPLocation.Name

 $ hg update tip; hg log -f org.adempiere.ui.swing/src/org/compiere/grid/ed/VLocation.java -l 3
 3 Dateien aktualisiert, 0 Dateien zusammengeführt, 0 Dateien entfernt, 0 Dateien ungelöst
 8462:ce681a208126 development	2013-02-08 nmicoud 	Improvement for locations
 8141:7f170d6a43f8 development	2012-12-13 richard1988 	IDEMPIERE-455 Discover and fix FindBugs problems / Eclipse warning -> not used
 7636:c31311312ffb development	2012-09-12 globalqss 	IDEMPIERE-417 Update BPLocation.Name

Solution 2: Deleting the not approved commit and continue with the private head

After that we know that the problem comes from the commit ce681a208126 on the private head. It has a conflict with fec3d762a863 on the swing branch. So we have to delete the wrong commit and can then merge with the swing head. You can't "delete" anything in a versioned system but you can redo it with the backout command.

 $ hg update -C tip
 $ hg backout ce681a208126
 $ hg commit -m 'backout ce681a208126'
 $ hg merge swing
 $ hg commit -m 'merge swing head'

please add more examples

...to be continued

Mercurial Bayen Best Practice

Contents