Technical status of CVS -> Mercurial migration

Status and technical details of switching the VCS for NetBeans sources to Mercurial.

Other pages of interest

• HgMigrationPlan and HgMigrationChecklist
• HgTrainingMaterials and HgTrainingDelivery
• HgHowTos
• HgTeamIntegration

Content migration script

In apisupportx/hgimport (in trunk). Expects to migrate ../.., i.e. containing NetBeans sources. No particular module list - check out . (everything). Only clean checkout supported (unbuilt sources). Any output created in apisupportx/hgimport/out.

Daily builder Artifacts should include several demo Hg repos. These will be recreated each day, so for testing purposes only.

Status: all standard IDE clusters buildable. Javadoc builds. NBMs for stableuc build. experimental modules build. JNLP builds. Tests build.

Script functions:

• Module paths normalized to abbreviated CNB with common prefixes implied; e.g. java/j2seproject -> java.j2seproject, core/progress -> api.progress, openide/loaders -> openide.loaders
  • regular naming eliminates guesses about where module sources are
  • flat structure should be more efficient, easier to search
  • look at a preview
• Several repos created, such as:
  • main with:
    • all modules in standard distro
    • perhaps all modules on stable UC
    • basic build infrastructure and IDE branding
    • test infrastructure
  • contrib with additional buildable modules
    • would for now expect to be checked out as subdir of main, perhaps using "forest" extension
  • www with */www (most importantly, testwww/www
  • misc with unbuildable modules, ...anything else uncategorized
    • truly obsolete stuff should be deleted from CVS trunk first
• .cvsignore files translated to .hgignore automatically
• new file paths should be automatically substituted in relevant files
  • */build.xml, */nbproject/project.properties, ...
  • need to check carefully for actual file paths, e.g. not all occurrences of string image should be replaced with o.n.m.image!
  • should produce as output a *.diff of all substitutions, for human review
  • complete translation table should be saved for future use
    • (for example, could be used by Sustaining to create an automatic translation script for patches created in new structure to be backported or vice-versa)
• files with excessively long Hg storage paths are not imported

Source reorgs are conservative with respect to build system: module file paths change, but not basic build logic.

Files with disposition TBD

Performance tests

performance
enterprise/performancetests
j2ee/performancetests
languages/performancetests
mobility/performancetests
uml/performancetests
visualweb/test/performance
web/performancetests

are now put in main/performance and subdirectories thereof. Oleg Khokhlov says this is OK.

Migrate history or not?

It is viable to import some CVS history into Hg.

Specifically, trunk revisions of text files will be imported. History of binary files will not be imported (just the last trunk revision). History of CVS branches will not be imported. History of files deleted in the CVS trunk will not be imported.

CVS branch names (e.g. release60) and tags applied to branches (e.g. release60-BLDwhatever) will not be imported. Trunk tags will be imported as Hg tags, though we will probably want to delete most of them later, since most are meaningless daily build tags. (In Hg, unlike CVS, tags are just part of versioned data, so deleted tags could be recovered if they were ever needed.)

This subset of history is enough to perform hg annotate and similar commands on files in the repository. You even get changesets (a single commit spanning multiple files) - though changes to binary files like icons, and file deletions, will not be represented.

Any text files mistakenly committed with CRNL line endings will also be converted to NL in the imported history.

.cvsignore files are not imported at all, since they are collected into a .hgignore file.

Importing full history would suffer from two problems:

1. The hg convert command aborts if it gets too many revisions at once. (This might be fixable using some tricks, but would be extra work.)
2. The initial repository size would be much bigger, making network clones slow and disk usage heavy. (Storing line-by-line diffs for text files which are present in the repo anyway only seems to add ~110Mb of extra space for the main repository, which is reasonable.)

Windows-specific notes

Standard IDE known to build on Windows, but more testing is in order.

To clone the repo on Windows, you must be sure to use a relatively short base path (up to around 50 characters), because of the unresolved issue with long repository filenames (see Hg bug #839 below).

Developers must commit text files with NL line endings. Howeber, CRNL <-> NL translation on Windows is not on by default with Mercurial. It can be enabled by editing the config file (e.g. C:\Mercurial\Mercurial.ini) to turn on cleverencode and cleverdecode mode. Autodetects binary files based on NUL. Seems to work as expected (IDE builds and runs successfully, at least). Repository after import should be free of text files containing CRNL.

Will have an incoming hook on public repositories to reject changesets with bad line endings. Otherwise Windows developers who forget to configure the encoder can cause trouble. (See Hg RFE #882 below.)

Server

http://hg.netbeans.org/

Users and authentication

We will want to import usernames (and passwords?) from the current netbeans.org auth DB.

One issue is what email address should be configured for the user as far as Hg is concerned. (This can be set in ~/.hgrc or $REPO/.hg/hgrc.) We want these to be predictable for purposes of disaster recovery, hg churn, etc. Probably jhacker@netbeans.org should be used in case jhacker is the login ID. (Or simply jhacker; Hg does not require an actual email address.) Tricky to enforce. One possibility is to set up an incoming changeset hook on the server which checks for non-*@netbeans.org addresses (or apparent usernames which are not in the database) in new changesets; if it finds any, send mail to those people asking them to configure Hg correctly.

Commit model

Main proposal is for staged propagation of commits through team branches, with test-based controls to prevent serious problems (e.g. uncompilable sources) in the master repository. Details: MercurialBuildInfrastructurePlan

TBD:

• What is granularity of "team"? 1-20 people?
  • Because with Hg you have a local repo, a "team of 1" means: commit at will, and once a day (or less) do a clean build w/ tests and commit. (In the morning! Not right before leaving work!) But no protection against developers who refuse to work this way.
• Who or what merges to master repo - dev lead? Automated process?
• What is the schedule for pushes to master? ASAP after tests pass? Every Monday for team #1, Tuesday for team #2, etc.?
• When do bugs get mark fixed in the bug tracker? When you commit to local repo? When you push to team server? When team pushes to master? Do you put changeset hash in bug database right away, or wait for some commit hook to add it for you?
• Does it really make sense to have a team repo clone, or should we instead use named branches to do possibly unstable commits?

Commit notifications

Mail

Hg comes with some script for sending out changes. It does not support sending to different people/aliases based on paths of files changed. But this can be fixed pretty easily with a small patch to notify.py.

RSS

Could perhaps have e.g.

http://hg.netbeans.org/rss/main?modules=o.o.fs,o.o.loaders,...

which would provide personalized RSS feeds of changes in certain areas only.

Code reviews

Crucible currently lacks Hg support.

Review Board is O/S and has Hg support.

CIA

Should set up NB in CIA. Hg includes an extension to make this easy.

Performance

Repository size

Affects download (initial clone) time. Also affects local disk usage, though hardlinks help.

Rename problem

Hg (as of 0.9.5) increases storage whenever you move files. See Hg bug #883 below.

Because of this problem, we need to do big source reorgs (as in migration script) now, not later.

Binaries

Upgrading e.g. libs/xerces/external/xerces-2.8.0.jar to libs/xerces/external/xerces-2.8.1.jar will result in both binaries being kept in revlogs in the repo. Over time repo size will grow, perhaps substantially. (Initial binary size: 100Mb out of 500Mb total for main repo. In CVS repo, **/external contains 227Mb of historical versions. All **/*.jar/zip, dating to before external dirs, are 2563Mb!)

Solution: HgExternalBinaries

Scan time

With a lot of files, a simple hg status can take some time.

INotify

Linux users can use the INotify extension. Huge speed improvement for certain operations. But still buggy and not yet recommended.

You will however need to run:

sudo sh -c 'echo 32768 > /proc/sys/fs/inotify/max_user_watches'

to use it on the "main" repository due to the large number of directories. The above works for one session; to make it permanent:

sudo sh -c 'echo "fs.inotify.max_user_watches=32768" >> /etc/sysctl.conf'

A Windows port would be great.

Local disk space

Hardlinks

For Unix users, local clones use hardlinks to reuse .hg storage. The actual checkout must be a full copy (in case editors do not create new inodes when saving changes). Should also work for Windows users if using NTFS.

Network clones of course cannot use hardlinks. It is possible to minimize disk usage (and clone time!) when you are creating a local clone of a server clone (e.g. a release repo) and you already have a local clone of master.

Mirrors

Since Hg is fully distributed, it is possible to set up mirrors easily. After cloning from a mirror, you need to edit .hg/hgrc to set the default parent repo.

You can create a local mirror of master on your own computer, too. (Use hg clone -U to skip checkout of tip.) This can be useful: do all pulls into this local mirror, and do most clones starting from it.

Training

TBD.

Collect URLs for useful summaries, tips & tricks, etc. from other teams.

Need list of best practices. At least, unlike CVS, it seems that best practices should actually work once you understand them.

IDE Support

MercurialVersionControl

Documentation

HgMigrationDocs

HgHowTos

Stuff from other Sun teams

Not externally available at the moment.

Java SE: Hg transition

Java SE: Hg general

Scenarios

Actual tested sequences of Hg operations to accomplish certain tasks.

TBD. Need to collect and test one by one, incl. performance.

Repeated merges in repo clones and named branches

Make sure merge tracking is OK.

Merge from server clone to server clone

Can you merge changes from one server-side clone to another? Do you have to make a separate clone of each?

Seems to work fine and you can do a local clone. You need to use hg clone -r using the revision of master in effect at the time the server clone was made (use tags!!), then update from it. You do not get hardlinks between .hg dirs in this case (see RFE below).

Hudson + Hg Bugs/Problems

Hudson does not support the Forest extension. Hudson RFE #1143

Hudson has difficulty linking to hgweb. Hudson bug #1038

Hudson should record the Mercurial ID of the repository in the build's metadata somewhere.

Attachments

mapping

42266 bytes