Nuxeo EP source are tracked using Mercurial from Selenic.
To install the hg command under Ubuntu / Debian :
Under Fedora Core, this should become:
If you need the help of a good UI, I suggest you tortoise HG
Mac OS X
Setting a username
If you plan to checkin in nuxeo's hg repositories, you should provide a valid user name. This is achieved by setting the username property in the .hgrc settings file.
Activating pre-integrated extensions
You should activate some pre-integrated extensions for working with nuxeo repositories. This is achieved by adding the following lines to the extensions section of your .hgrc.
Overview and online documentation
Mercurial is a completely decentralized system. Every cloned repositories contain a working directory and a store of complete project's history, thus allowing offline and parallel development.
The working directory contains a copy of the project's files at a given point in time, ready for editing.
The store contains a sufficient data to provide any file at any revision or tag from any branch.
Mercurial groups related changes to multiple files (commits) into single atomic changesets. Every commit generates a changeset recording the state of the working directory relative to its parents, so merging is really easier and more efficient than with other SCM.
Mercurial home site
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 FAQ and some workarounds or guidelines for specific cases.
Nested repositories and Forest extension
When migrating from Subversion to Mercurial, we looked for a feature replacing "svn externals".
We have used the Forest extension for a while but this Mercurial extension is no more maintained.
Since the "nested repositories" (since Mercurial 1.3) are still an experimental feature and do not address our needs, we don't use them.
So, there is currently no Mercurial solution for running a command on a "full" Nuxeo repository including its sub-repositories, such as cloning full Nuxeo sources.
Nuxeo provides [NXDOC:Shell scripts|#shellscripts] for managing repositories containing sub-repositories (see
Nuxeo common usage
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" Mercurial repository is https://hg.nuxeo.org/.
We've set some Mercurial “hooks” on the central repositories filtering changesets according to whether they comply to the following rules:
- Changesets must not be blacklisted.
- Even with the Mercurial's two-steps committing process (commit then push), it may happen to push erroneous changesets with really no interest or making trouble in code history. In such cases, it's a good thing to "strip" these changesets, removing them from history.
- We usually blacklist a changeset after having stripped it, to be sure nobody will push it again in case it has been pulled before being stripped.
Error message is:
- Changesets are in an allowed branch.
- We make an extra use of branches: for long-time developments, prototype or spike solutions, ease parallel changes and give each developer merging responsibility of its code. Branches have "stable/main", "maintenance/release" or "development/test" purpose.
- Depending on the project we use white or black lists for branch names.
- On some projects, for instance, we blacklist the “default” branch to avoid confusion or lack of information about current version.
- Changesets do not result in two heads for the same branch.
- Changesets that have a given branch tag, but have no child changesets with that tag are called branch "heads". Mercurial identifies branches depending on their history so there may be two separate branches with the same name in case of concurrent changes made on a branch which were based on different parents. Of course, such situation is abnormal and must be fixed. This hook will prevent a developer from pushing changesets resulting in homonym branch heads.
- Rule is: always pull before trying to push. If your local changes drive to multiple heads with same branch name, you must merge them before pushing.
- User for changesets must be valid.
- For code history readability, usernames must be formatted like “John Doe <email@example.com>”.
This hook will generate a mail to the public mailing list <firstname.lastname@example.org> for every changeset (except "merging" changesets which are filtered out).
- Build trigger
This hook launches a build in our continuous integration system: http://qa.nuxeo.org/. Using a trigger ran at every commit is saving a lot of bandwidth compared to regularly pulling the repository to check for code changes.
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.
Branch layout and policy
We usually define stable, maintenance and development branches.
- Stable, next to release branch
Often called "main" branch, this named branch is hosting the most-recent code.
Stable branch is of course under continuous integration. Merge and commits must be double-checked; as much as possible, changes have been firstly tested and validated on a development branch or in developer's working directory.
Nuxeo uses stable branches named x.y (i.e. 5.4). New features, eventually breaking API, are developed on the last x.y (currently 5.4). There's almost no new feature on other branches which have both stable and maintenance purpose and are gathering fixes from x.y.z releases.
I.e. 5.4 branch is hosting 5.4.0-SNAPSHOT code which will lead to 5.4.0 release. 5.3 branch is hosting 5.3.3-SNAPSHOT code and may lead to 5.3.3 release.
- Maintenance, patch branch
When releasing, a dedicated branch is created and then tagged. This branch is used for creating minor versions releases.
Fixes done on it will be merge on stable branch(es); fixes from stable branch(es) may be backported on this maintenance branch to generate patches or minor releases.
Maintenance branch are rarely under continuous integration as there is no more work on them except fixes and backports.
I.e. 5.1.6 branch is hosting 5.1.6 code, tagged as release-5.1.6, and may lead to minor versions releases such as 5.1.6.x.
- Development branches
Developers are strongly encouraged to use as much branches as they need (one per JIRA issue or per development iteration). Those branches may or not be automatically tested, their purpose is code isolation while it is unstable: they are merged to main dev or stable branch after being fully tested.
I.e. 5.2-NXP-9999-some_user_story will host code linked to implement some user story until the end of the iteration (or some point the code is considered mostly stable and usable).
Here are some recommended practices using Mercurial at Nuxeo.
- Update and commit often. It will ease future merge tasks.
- Always reference a Jira issue at the beginning of commit comments: i.e. “NXP-9999 – sample task, remove code using deprecated API”.
- Long time work should be done in a separate branch; named with the associated Jira issue and a short description: i.e. “NXP-9999_longtime_work”
Check what you've changed before committing and what you've committed before pushing.
- Never “force” a push unless being sure it has to be done.
Useful scripts, commands and tips
The following Mercurial commands are given with useful parameters into brackets, other parameters may be available.
hg help [NXDOC:COMMAND] for available commands listing or help on a specific command.
Nuxeo shell and batch scripts
They are mainly used for Nuxeo repositories which contain sub-repositories. Those scripts provide an alternative to the Forest extension.
hgf function runs a hg command into current and nuxeo-* subdirectories:
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 had on nuxeo before 5.4 (i.e. 5.2/1.5). It uses inverted polish notation.
Check incoming changes
Check uncommitted changes
This gives you modified (M), added (A), removed (R) and uncontrolled files (?) .
hg addremove [NXDOC:-s 100] and/or
hg ci to commit these changes.
Check current branch, working directory status
This gives you current revision (with a + if it has been locally modified but not yet committed), current branch name and, if your current revision is the latest modified head, the
Show the parents of the working directory or revision.
Show latest changeset, existing heads, branches and tags
This gives you the log of the latest modified head, aka
Branches marked as “inactive” are not considered as
heads, they haven't been modified since they were merged into another branch (i.e. Nuxeo 5.1 branch is always “inactive” as we ask the developers to always merge — forward port — their changesets from 5.1 to 5.2 and so on.
This is useful for example to identify multiple heads with same name that must be merged.
Gives all available tags and their corresponding revision and branch.
Follow changesets history
Show revision history of entire repository or files.
Same as log but with a graphical view (requires GraphLog extension).
Show changeset information per file line. Useful when you need to know who changed a specific part of a file.
Strip a revision and all later revisions on the same branch.
Apply one or more changegroup files. Used to revert a strip.
Reverse effect of earlier changeset. Contrary to strip, backout only removes one changeset, not the children revisions.
Roll back the last transaction.
Restore individual files or directories to an earlier state.
hg pull -u but prefer
hg pull && hg up, there are sometimes issues with the first one. Also, check your current branch with
hg id after
hg clone as it goes by default on
Advanced usage and specific use cases
Merging policy from stable to development branch
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.
Merging policy from development to stable branch
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 - TDD).
Functional tests are up-to-date to cover the new functionalities.
The development branch to merge must have been fully tested:
- developers have successfully run Unit Tests
- developers have functionally validated last developments
automated builds have run on development branch
At this moment, development branch can be merged on stable one:
Use "-f" only if stablebranch was no more a head.
Managing multiple heads
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).
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:
Checks before pushing
In case of doubts, before pushing, you can check what you've done with multiple commands:
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.
Later, to update ~/repo-local/ for instance:
hg fetch can be used to pull, merge, commit but it is for experienced users, we recommended being familiarized with unitary commands before using fetch.
Activate Fetch feature in your
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, ...).
Changing descriptions of changesets not pushed yet
You need to have mqueue extension activated in your
Check what you want to change and haven't pushed
Import your changesets you want to modify in the queue. The changesets will be moved to the queue branch. For example, to import the changesets from 692 to 695.
Extract the queue into the filesystem. At this stage, your changesets won't be visible from your log. (-a to pop all the changesets from the queue)
mqueue will then create diff files (one for each changeset) in the folder .hg/patches. You can modify these files, changing the description or even changing the patches.
Once you have made your changes, put them back to the queue.
Finish with moving your changeset back to your branch
That's all :)
Other Mercurial related pages