http://mercurial.selenic.com/wiki/Mercurial.

There are “getting started” and “using Mercurial” documentations, even some help for developers used to other SCM systems.

You will find useful tips and scripts in Nuxeo Wiki FAQ: http://doc.nuxeo.org/xwiki/bin/view/FAQ/DownloadingNuxeoSources and some workarounds or guidelines for specific cases.

Since the "nested repositories" came only with Mercurial version 1.3 and are still an experimental feature, we chose to rely on the Forest extension when migrating from Subversion to Mercurial for replacing "svn externals".

This is not mandatory for working with Nuxeo. This extension mainly provides easier way to run a command on a "full" nuxeo repository including its sub-repositories, such as cloning full Nuxeo sources. For example, those repositories have sub-repositories: nuxeo-addons, nuxeo, ...

Although Mercurial is decentralized, Nuxeo hosts “centralized” Mercurial repositories which are the “reference” repositories, they are backed up and changesets made on local repositories must finally be pushed on those remote repositories. The public "centralized" repository is https://hg.nuxeo.org/.

We've set some “hooks” on the central repositories filtering changesets according to whether they comply to the following rules:

Setting such hooks was not mandatory but they guarantee the developers are following a few basic rules and prevent them from simple mistakes.

It is sometimes possible to force a push in spite of the hooks, when you know the hook message is not an error but a warning and it can be securely circumvented.

We usually define stable, maintenance and development branches.

They are mainly used for Nuxeo repositories which are constructed as a forest of sub-repositories. Forest extension provides quite equivalent functions but both are complementary.

hgf function runs a hg command into current and nuxeo-* subdirectories:

hgf() { 
  for dir in . nuxeo-*; do 
    if [ -d "$dir"/.hg ]; then 
      echo;echo "[$dir]" 
      (cd "$dir" && hg "$@") 
    fi 
  done 
}

hgf.bat:

@echo off 
set PWD=%CD% 
echo [.] 
hg %* 
for /d %%D in (nuxeo-*) do ( 
echo [%%D] 
cd %PWD%\%%D 
hg %* 
) 
cd %PWD%

hgx function is a little more complex and tied to nuxeo repositories as it runs a hg command into current and nuxeo-* subdirectories managing with the two version numbers we have on nuxeo (i.e. 5.2/1.5). It uses inverted polish notation.

hgx() { 
  NXP=$1 
  NXC=$2 
  shift 2; 
  if [ -d .hg ]; then 
    echo $PWD 
    hg $@ $NXP 
    # NXC 
    (echo nuxeo-common ; cd nuxeo-common; hg $@ $NXC || true) 
    (echo nuxeo-runtime ; cd nuxeo-runtime; hg $@ $NXC || true) 
    (echo nuxeo-core ; cd nuxeo-core; hg $@ $NXC || true) 
    # NXP 
    (echo nuxeo-theme ; cd nuxeo-theme; hg $@ $NXP || true) 
    [ -d nuxeo-shell ] && (echo nuxeo-shell ; cd nuxeo-shell; hg $@ $NXP || true) || (echo ignore nuxeo-shell) 
    [ -d nuxeo-platform ] && (echo nuxeo-platform ; cd nuxeo-platform && hg $@ $NXP || true) || (echo ignore nuxeo-platform) 
    [ -d nuxeo-services ] && (echo nuxeo-services ; cd nuxeo-services && hg $@ $NXP || true) || (echo ignore nuxeo-services) 
    [ -d nuxeo-jsf ] && (echo nuxeo-jsf ; cd nuxeo-jsf && hg $@ $NXP || true) || (echo ignore nuxeo-jsf) 
    [ -d nuxeo-features ] && (echo nuxeo-features ; cd nuxeo-features && hg $@ $NXP || true) || (echo ignore nuxeo-features) 
    [ -d nuxeo-dm ] && (echo nuxeo-dm ; cd nuxeo-dm && hg $@ $NXP || true) || (echo ignore nuxeo-dm) 
    [ -d nuxeo-webengine ] && (echo nuxeo-webengine ; cd nuxeo-webengine; hg $@ $NXP || true) || (echo ignore nuxeo-webengine) 
    [ -d nuxeo-gwt ] && (echo nuxeo-gwt ; cd nuxeo-gwt; hg $@ $NXP || true) || (echo ignore nuxeo-gwt) 
    (echo nuxeo-distribution ; cd nuxeo-distribution; hg $@ $NXP || true) 
  fi 
}

hgx.bat:

@echo off 
set PWD=%CD% 
set NXP=%1 
set NXC=%2 
echo [.] 
hg %3 %NXP% 
for /d %%D in (nuxeo-platform nuxeo-distribution nuxeo-theme nuxeo-shell nuxeo- 
webengine nuxeo-gwt nuxeo-services nuxeo-jsf nuxeo-features nuxeo-dm) do ( 
echo [%%D] 
cd %PWD%\%%D 
hg %3 %NXP% 
) 
for /d %%D in (nuxeo-core nuxeo-common nuxeo-runtime) do ( 
echo [%%D] 
cd %PWD%\%%D 
hg %3 %NXC% 
) 
cd %PWD%

hg in [-p] [-r REVISION]

hg st [--rev REVISION]

hg id [-inbt]

hg parents [-r REVISION]

hg tip [-p]

hg branches [-a]

hg heads [-r REVISION] [REVISION|BRANCH_NAME]

hg tags

hg log [-r REVISION] [-l LIMIT] [-p]

hg glog [-r REVISION] [-l LIMIT] [-p]

hg ann [-r] [-f] [-u] [-d] [-n] [-l]

hg strip REVISION

hg unbundle FILE...

hg backout

hg rollback

hg revert [-a] [-r REVISION] FILE...

Merge stable branch on your development one as much as possible. It can be automated at morning and then manually done day by day each time there is some work merged on stable.

hg pull && hg up -C devbranch
hg merge stablebranch && hg ci -m”automated merge from stablebranch” [-u...] && hg push

See http://svn.nuxeo.org/nuxeo/tools/mercurial/automerge.sh.

It happens at the end of a development iteration, when code to merge is implementing a group of User Stories/Use Cases.

Unit tests are up-to-date to valid the new code (see test-driven development recommendations).

Functional tests are up-to-date to cover the new functionalities.

The development branch to merge must have been fully tested:

At this moment, development branch can be merged on stable one:

hg pull && hg up -C stablebranch
hg merge devbranch && hg st
hg ci -m”merge from devbranch – NXP-9999 ...”
hg push [-f]

Use “-f” only if stablebranch was no more a head.

If two developers worked on the same branch with different parents, it may result in two simultaneous branches with the same name (see server-side hooks).

$ hg push 
pushing to https://hg.nuxeo.org/somerepository
searching for changes 
abort: push creates new remote heads! 
(did you forget to merge? use push -f to force)

In such case, the developers won't be able to push their changesets until they have merged the two branches. "hg heads branchname" will show the multiple heads and their changeset identifiers.

Simplest way is to switch his working directory to the other developer's revision and merge his own code:

hg up -C otherRevision 
hg merge ownRevision
hg st 
hg ci -m”merge two heads” 
hg push

In case of doubts, before pushing, you can check what you've done with multiple commands:

hg out [-p] [-r REVISION]
hg glog [-l LIMIT] [|less] 
hg heads someBranch

Thanks to Mercurial which is decentralized, even if Nuxeo's repositories are not, you can pull from Internet to a local repository and then pull from this repository. Then, you can update the .hg/hgrc file to bind it on the central repository or continue using the local one, pushing on it and then pushing changesets from it to the remote one.

hg clone https://hg.nuxeo.org/somerepository/ ~/repo-remote/ 
hg clone ~/repo-remote/ ~/repo-local/ 
cd ~/repo-local/
# some work…
hg ci -m”NXP-9999 - some work” && hg push 
cd ~/repo-remote/ && hg pull 
# usual checks (heads, merge, …) 
hg push

Later, to update ~/repo-local/ for instance:

cd ~/repo-remote/ && hg pull
cd ~/repo-local/ && hg pull && hg up

“hg fetch” can be used to pull, merge, commit but it is for experienced users, it's recommended to first being familiarized with unitary commands.

Mercurial Queues are an advanced group of Mercurial functions. Whereas not very easy to apprehend, they are powerful tools.

You can for instance transform a group of changesets made on a wrong branch to patches being then re-applied on the right branch, while editing and changing anything in those changesets (user, comments, ...).

See http://mercurial.selenic.com/wiki/MqExtension or Mercurial: The Definitive Guide by Bryan O'Sullivan.

If you are already familiar with the Checkstyle Eclipse plugin, just configure it to use the checkstyle.xml at the root of the nuxeo sources: http://hg.nuxeo.org/nuxeo/file/5.2/checkstyle.xml.

TODO

TODO

Maven Parent POM file gives a lot of useful information. Take care to fill in you project's pom.xml file:

All these tags are intelligently inherited so that, if you're project's Maven parent is nuxeo-ecm or one of its children, you don't have to repeat informations such as "organization", "licenses", "mailingLists", "issueManagement". Also, when working on a project with sub-modules, it's only necessary to set "scm" on the parent POM.

Adding a project under continuous integration in Hudson requires: