Changes between Initial Version and Version 1 of TracMercurial

Timestamp:

Nov 2, 2005, 7:05:57 PM (19 years ago)

Author:

Christian Boos

Comment:

Initial documentation for the hg-plugin

TracMercurial

@@ +1 @@
+= Mercurial Plugin for Trac (#1847) =
+
+There is an experimental plugin for Trac [milestone:0.9] which enables
+[http://www.selenic.com/mercurial Mercurial] to be used 
+instead of [http://subversion.tigris.org Subversion]
+for the VersioningSystemBackend.
+
+
+== Download and Installation ==
+
+==== Trac ====
+The plugin needs a slightly modified version of Trac 0.9, 
+which offers support for pluggable SCM backends.
+This version can be found in
+  source:branches/cboos-dev/versioncontrol/vc-refactoring
+Simply do:
+{{{
+svn co http://projects.edgewall.com/trac/branches/cboos-dev/versioncontrol/vc-refactoring trac-for-hg
+}}}
+and install from there (`cd trac-for-hg; python setup.py install`).
+
+
+The plugin itself is available from
+  source:branches/cboos-dev/versioncontrol/hg-plugin
+Check it out, too:
+{{{
+svn co http://projects.edgewall.com/trac/branches/cboos-dev/versioncontrol/hg-plugin .
+}}}
+and create an "egg" from there (`cd hg-plugin; python setup.py bdist_egg`).
+Note that you'll need
+[http://peak.telecommunity.com/DevCenter/setuptools setuptools] 
+>= 0.6 for that (I used setuptools-0.6a5).
+
+The initial release of the plugin was made at r2472 and works
+well with the vc-refactoring branch at that revision.
+
+
+==== Mercurial ====
+The plugin has been tested with Mercurial 0.7 and a few later versions
+(upto Changeset 1481:acd1832ebf31 from http://selenic.com/hg).
+It won't work with earlier versions.
+You can download hg from 
+[http://www.selenic.com/mercurial/wiki/index.cgi/Download Hg:Download].
+
+
+== Configuration ==
+
+The plugin egg can be added to the `plugins` folder of an existing environment,
+or to a brand new environment. Note that if you create a new environment, it's
+currently necessary to ''not'' specify the repository directory during the
+`initenv` step (''this will probably be fixed soon'').
+
+In either case, you'll need to specify the backend scheme to be used
+(here `hg:`) in front of the actual repository location, in TracIni:
+{{{
+[trac]
+repository_dir = hg:/path/to/my/hg/repository
+}}}
+
+Also, you'll need to explicitely disable the SVN components:
+{{{
+[components]
+trac.versioncontrol.svn_fs.* = disabled
+}}}
+''Note: that constraint will most certainly be lifted in the future''
+
+
+== Features ==
+
+The Mercurial support is pretty basic, but works well. I've tested that 
+on the Mercurial repository itself and the performance is quite good, 
+even if there's currently ''no'' caching in the database
+(I'm still not decided if that's a feature or a bug).
+
+For those used to Subversion in general and Subversion repository browsing
+in Trac in particular, there are a few differences worth noting.
+
+=== Mercurial Changesets ===
+
+==== Changeset Navigation ====
+
+In Mercurial, the ''Previous Changeset''/''Next Changeset'' navigation is 
+''not'' purely sequential, as it is in Subversion.
+Instead of a ''flat'' history of successive changesets, we actually navigate
+a DAG of changesets. 
+This means a changeset can have multiple parents (0, 1 or 2) and multiple
+children as well (0 to n). 
+
+Therefore, ''Previous Changeset'' is a link to the first parent, 
+and ''Next Changeset'' is a link to the first children.
+In case there are additional parents or children, these are shown as 
+additional changeset properties (''Parents'' or ''Children''), 
+placed below the ''Author'' property and above the ''Message'' property.
+
+[[Image(hg-plugin-changeset.png)]]
+
+Another additional changeset property is the list of ''Tags'' that
+might be associated with a changeset.
+
+==== Wiki syntax ====
+
+The Wiki syntax has been extended a bit, to cope with the hexadecimal
+notation of hg changesets. E.g `[8ef2]` would link to the changeset 
+8ef2ba892518c115170398ec754bd1c27cab271f ...
+Also, it is possible to refer to changesets using the changeset: prefix 
+(or cset: or chgset:, for hgweb compatibility). 
+The tag: prefix can be used to refer to symbolic tags, although this is not
+a requirement (using. e.g. `cset:tip` would work too). 
+Finally, the branch: prefix has a special meaning, as this will not select
+the specified revision, but the head which is reachable from that revision.
+
+
+=== TracBrowser changes ===
+
+The TracBrowser ''View revision'' form has been extended with
+pulldown menus for jumping to a given tag or branch (in Mercurial, 
+a branch within a repository corresponds to a head, i.e. a 
+changeset without children): [[Image(hg-plugin-browser.png)]]
+
+
+== Bugs and Limitations ==
+
+There are still a lot of things that can be improved.
+
+=== Features that Trac+svn has but not currently implemented for Trac+hg ===
+
+ * History doesn't follow copy/move operations
+ * No ''path history'' mode (i.e. show all create/delete operations that 
+   affected a given path)
+
+=== Multi-repository support ===
+
+First and foremost, even if Mercurial allows intra-repository branching, 
+it strongly supports the use of branching by cloning the full repository.
+Therefore, it is common to have a lot of hg repositories around, each
+devoted to the implementation of some particular feature.
+
+Trac should support this by the way of multiple repository support 
+within a single environment (see #2086).
+
+
+=== Arbitrary diff support ===
+
+The TracDiff features should be supported by TracMercurial too.
+
+
+=== To cache or not to cache? ===
+
+I happen to like to current database-free implementation of the Mercurial
+support.
+It makes it quite easy to change the `repository_dir` on the fly, and this 
+flexibility is good. Also, hg being remarkably efficient, as everybody knows,
+the performance is quite good... Except in one case, getting the history
+of a directory. There, I suspect that the database cache would be quite useful.
+But I have yet to try on a big repository (e.g. the kernel) with either
+approach before concluding. In any case, thanks to the vc refactoring,
+the possibility will be offered to choose between a direct access or a 
+cached access, as it's done for Subversion, svn: (cached) or
+direct-svn-fs: (direct access).
+
+
+=== Cool Features ===
+
+''Wild ideas'' section...
+
+==== Visualize branches and merges ====
+
+There should be a way to show graphically the branch and merge points within
+the revision log view. Not something as fancy as `hgk`, but nonetheless
+something that will make the changeset relationships immediately obvious.
+
+==== Search over the source ====
+
+A search provider could do the equivalent of an `hg grep`.
+
+==== Highlight Conflict Resolution ====
+
+While visualizing changeset diffs for merge changesets, we already
+show the changes relative to both parents, which helps to understand
+how conflicts (if any) were solved. But this can be improved by 
+specifically highlighting lines that differs from both parents.
+
+==== ''Add your cool feature here...'' ====
+
+----
+
+== Implementation Notes ==
+
+I'm interested in feedback concerning the code, in particular: 
+ * concerning Trac, there are only a few changes to the standard modules,
+   !ChangesetModule (the additional properties) and !BrowserModule
+   (the tags and branches support). Those changes could possibly be promoted
+   to the generic level, therefore removing the need for having to explicitely
+   disable the SVN components...
+ * concerning Mercurial, I'm pretty sure I did things in a sub-optimal
+   way, as I was discovering the guts of hg while writing the plugin. 
+   Therefore, I'll be pleased to get tips for improvements.
+
+'' -- ChristianBoos ''