This page covers Mercurial notes for developers, covering Amara and Akara 2.x.
Contents
Useful background references:
The project trunks are at:
http://bitbucket.org/uche/amara/ (alternative: http://hg.xml3k.org/amara )
http://bitbucket.org/uche/akara/ (alternative: http://hg.xml3k.org/akara )
But branches can be anywhere.
What Mercurial version was the source of my build?
Assuming the person who builds an Amara package does so from a Mercurial repository, the setup.py should set up a lib/__hgid__.py which provides information about the identity of that repository.
A user can get this ID as follows:
python -c "from amara.__hgid__ import HGID; print HGID"
Using bundles
If you want to contribute to or experiment with Akara code without going through the full set-up process as a developer, you can work locally and then submit patches in the form of Mercurial bundles.
Reviewing bundles
If you receive bundles you can examine it using commands such as the following:
$ hg in bundle.hg # view the changesets added by the bundle $ hg -R bundle.hg log # view the log of repo+bundle $ hg -R bundle.hg diff -r tip # compare the working dir to the bundle's tip $ hg -R bundle.hg cat -r tip foo.txt # extract a particular file
See below for more on bundles
Creating branches
You can pretty much create a branch wherever you like. It's useful to also mount them to the Web. For WebFaction users, see instructions here.
Creating a branch on akara.info
If you have SSH access to akara.info, you can host branches there. It might be better for you to just do so on your own BitBucket account.
Assuming you've already cloned from main or another branch, make sure to hg commit any work you've already done to your local repo but do not push to main. Then create the branch on the server as follows:
cd path/to/local/repo hg commit -m "Preparing to branch" #If necessary hg clone ssh://hg.akara.info//var/local/hg/amara/branches/$BRANCHNAME
BRANCHNAME should be brief but descriptive
This assumes you have SSH developer access to hg.akara.info. Of course you can choose to make the destination any Mercurial server you like.
You should probably rename the local folder to reflect the branch, and make sure you edit its .hg/hgrc to make its default destination the branch rather than main
Merging
Some useful tips and trick when merging from a branch:
Main resource on merging: http://hgbook.red-bean.com/read/a-tour-of-mercurial-merging-work.html
If there were files moved about in the branch, see: http://hgbook.red-bean.com/read/mercurial-in-daily-use.html#chap:daily.copy , heading "Renaming files and merging changes"
Sample sessions etc.
Sample branch merge session
This is an example of a merge from branch into trunk. It dates from a time when the trunk machine was "hg.4suite.org", so its out of date as far as the current locations of things, but the procedural information is still correct and useful.
The very clear Mercurial book covers merging. The following is an example specific to the hg.akara.info repositories.
Starting from a trunk clone's working dir, and having done hg pull -u to be sure:
$ hg pull ssh://hg.akara.info//home/dalke/amara-test pulling from ssh://hg.akara.info//home/dalke/amara-test searching for changes adding changesets adding manifests adding file changes added 172 changesets with 506 changes to 376 files (+1 heads) (run 'hg heads' to see heads, 'hg merge' to merge)
Notice the message about multiple heads:
$ hg heads changeset: 544:8946ff4525ac tag: tip user: dalke date: Sat Jul 18 23:29:38 2009 +0200 summary: removed cruft changeset: 372:2f60d89b1453 user: Uche Ogbuji <uche@ogbuji.net> date: Fri Jul 24 08:23:45 2009 -0600 summary: Update demos. Refine approach to common namespace mappings
Wade into the merge:
$ hg merge merging amara/namespaces.py and lib/namespaces.py to lib/namespaces.py merging amara/xpath/util.py and lib/xpath/util.py to lib/xpath/util.py merging setup.py warning: conflicts during merge. merging setup.py failed! merging test/writers/test_node_print.py 352 files updated, 3 files merged, 277 files removed, 1 files unresolved use 'hg resolve' to retry unresolved file merges or 'hg up --clean' to abandon
I used a mercurial installation without graphical 3-way merge, but such tools might be useful to some. Windows and Mac users, for example should use the convenient package here.
Notice the conflict of setup.py which Mercurial couldn't manage the merge automatically. I edited the file and searched for the conflict marker, finding:
<<<<<<< local
py_modules=['amara.tools.atomtools', 'amara.tools.rdfascrape', 'amara.tools.kekule', 'amara.tools.scrapesniff'],
package_dir={'amara.test': 'test', 'amara.tools': 'demo'},
=======
py_modules=['amara.tools.atomtools', 'amara.tools.rdfascrape'],
package_dir={'amara':'lib', 'amara.test': 'test', 'amara.tools': 'demo'},
>>>>>>> otherI merged by hand, resulting in:
py_modules=['amara.tools.atomtools', 'amara.tools.rdfascrape', 'amara.tools.kekule', 'amara.tools.scrapesniff'],
package_dir={'amara':'lib', 'amara.test': 'test', 'amara.tools': 'demo'},Notice I removed the conflict markers. I ran the tests to make sure things looked OK (cd test; sh testall.sh), then signaled the all clear:
hg resolve -m setup.py #use hg resolve -l to list files awaiting resolution
I wrapped up with hg commit; hg push as usual.
Sample use of bundles
Dave Beazley made a lot of changes, and wanted to share them with Uche. He use hg bundle filterless.hg and then sent that file to Uche. Uche did:
$ cd some/working/dir $ hg clone http://bitbucket.org/uche/amara/ destination directory: amara requesting all changes adding changesets adding manifests adding file changes added 660 changesets with 3193 changes to 1420 files updating to branch default 871 files updated, 0 files merged, 0 files removed, 0 files unresolved $ cd amara/ $ hg unbundle filterless.hg adding changesets adding manifests adding file changes added 1 changesets with 11 changes to 11 files (run 'hg update' to get a working copy) $ hg up 11 files updated, 0 files merged, 6 files removed, 0 files unresolved $ hg log | less #In order to find the most recent changeset that was not in this bundle (4496e5c60cef) $ hg diff -r 4496e5c60cef | less #In order to review the changes
Note: Uche could have used hg incoming etc before doing hg up