How to Write and Land Nanojit Patches

Adobe and Mozilla share a copy of Nanojit. This means that landing nanojit patches is a bit complicated, but experience has taught us that this is much better than having separate versions of nanojit.

(Note:  this document is called NanojitMerge for historical reasons -- Adobe and Mozilla used to have separate copies of Nanojit, but this was a maintenance headache so they were merged. The first version of this document was written just after that merge occurred.)

Resources

Nanojit development now takes place on a single shared repository nanojit-central.

• Repository: https://hg.mozilla.org/projects/nanojit-central (or clone ssh://hg.mozilla.org/projects/nanojit-central if you want to actually commit changes)
• Tinderbox: https://tinderbox.mozilla.org/showbuilds.cgi?tree=Nanojit
• Commit log: https://hg.mozilla.org/projects/nanojit-central/shortlog/
• IRC channel: irc.mozilla.org #nanojit

Procedure

The first thing to understand is that there are now three copies of nanojit in public mozilla.com repositories: one in nanojit-central, one in tracemonkey, one in tamarin-redux.  We land patches initially in nanojit-central, and those landings are followed up with semi-automated landings on tracemonkey and tamarin-redux.  These follow-up landings on tracemonkey and tamarin-redux will overwrite any changes made to nanojit in tracemonkey and tamarin-redux!  So, do not land nanojit changes directly to the tracemonkey and tamarin-redux repositories!

The following files in TraceMonkey are from Nanojit:

• Everything in js/src/nanojit/
• Everything in js/src/vprof/

Scenario 0: a common prefix for all scenarios

• Make private clones of all three repositories: nanojit-central, tracemonkey and tamarin-redux.  Here's how to clone and build nanojit-central:

  $ hg clone ssh://hg.mozilla.org/projects/nanojit-central
  $ cd nanojit-central
  $ autoconf
  $ mkdir build
  $ cd build
  $ ../configure
  $ make
  $ make check
  

• Learn and setup automated testing for all three repositories.
• Write a script for copying patches between repositories, it'll come in useful.

Scenario 1: creating an internal (ie. Nanojit-only) patch

• Write the patch in whichever repository you like.  For Mozilla people it's probably best done in your tracemonkey repo, for Adobe people it's probably best done in your tamarin-redux repo.
• Once the patch seems ready, copy it to the other two repositories and test it.  [njn: It's possible that the other TM/TR public repo hasn't been updated from nanojit-central sufficiently recently, in which case the patch won't apply cleanly.  If the breakage is minor you'll be able to fix it by hand.  If it's major you'll need to do a private update of that other repo in order to test.  But don't push that update, as that should only be done by a member of that public repo.]
• Once it passes testing, file the patch to Bugzilla (file a bug under the "Nanojit" component in the "Core" product) and get a review. Generally, patches by Mozilla people should be reviewed by Adobe people and vice versa.
• Once it passes review, land it on nanojit-central, mark the bug's whiteboard as fixed-in-nanojit, and note the revision in a comment. (Note that nanojit-central revision URLs have the form https://hg.mozilla.org/projects/nanojit-central/<revid>, ie. there is a projects/ subdir in there.  You might find it easier to just cut-and-paste links from the commit log.)
• You're done, but watch the Nanojit tinderbox for breakage.

Scenario 2: creating an external patch

• Write and test the patch, as in scenario 1 above.
• Split the patch into three parts:  nanojit, tracemonkey, tamarin.  File them all in a single bug.  Reviews should involve people from both Mozilla and Adobe.
• Once all the patches pass review, land the nanojit patch on nanojit-central and mark the bug as fixed-in-nanojit. Whoever does the next TM/TR update (scenario 3 below) will deal with the other patches.

Scenario 3: doing a periodic NJ-to-TM/TR update

This step is only done by certain people.  nnethercote usually does it for Mozilla, edwsmith and stejohns usually do it for Adobe.  Note that you'd only do this for your company's TM/TR repo, ie. Mozilla people for TM, and Adobe people for TR.

• Propagate all recent nanojit-central changes to your local TM/TR repo.  For tracemonkey, use the "make update-nanojit" target (it requires that Mercurial's "convert" extension be enabled;  add "hgext.convert =" to your .hgrc file under "[extensions]").  For tamarin, use the update-nanojit.sh script.  Note that updating will clobber the contents of the nanojit/ directory in your private TM/TR repo.  It will also generate a commit that updates the nanojit-import-rev file in your target repository;  this file records which commits have been copied over from nanojit.
• Build and test the changes.  In the easy case, you'll have a consistent TM/TR repo.  Land the TM/TR changes.  Then for each revision involved, mark its whiteboard as fixed-in-tracemonkey or fixed-in-tamarin.  You're done, but watch the tinderbox.
• In the hard case, you'll have a broken TM/TR repo.  This is because one or more recent external patch(es), P, landed on the other (TR/TM) repo, thus changing NJ's API but your TM/TR repo hasn't been updated to match the API change.  In this case, you have to look through the converted revisions you're about to push (run hg outgoing to list them) and figure out which patch(es) caused the breakage. Then find the corresponding bug(s) and commit the (hopefully already-reviewed!) TR/TM portion of the patch(es) on top of your current, un-pushed tip. At this point the set of changes you are about to push will consist of a sequence of converted revisions from nanojit-central, followed by one of more "fixups" to TR/TM to make them work properly. Test this entire group and land them with a single hg push. Then update the whiteboard for the each such bug P and add a comment URL.  And likewise for all revisions involved in the update.
• You're done, but watch the TM/TR testing results (tbpl or buildbot).
• If you ever want to "undo" revisions you copied from nanojit-central, you can backout copied revisions using the existing mercurial "backout" command in your target repository. If you do so, the next time you copy revisions from nanojit-central to your target repository, the script will re-copy the backed-out revisions, as well as those that occurred after. You can explicitly manipulate the revision from which the copying process begins by writing a nanojit-central revision ID to the file nanojit-import-rev, held in your target repository. If you are at all confused about this, ask in #nanojit IRC.

Scenario 4: if you break something

• If you land a patch that breaks nanojit-central, and then land a follow-up fix, it's a good idea to ensure the follow-up fix gets merged to TM and TR as soon as possible.  Otherwise, it might be possible that the broken patch gets pulled into TM/TR but the fix doesn't for quite some time, which will cause problems for others in the meantime.  See https://bugzilla.mozilla.org/show_bug.cgi?id=529900 for an example.