1. Summary

	This project proposes to add the source code management (SCM)
	system Mercurial[1] to the SFW consolidation for delivery on
	Solaris.

	This project requests a Minor release binding.

2. Background

	The OpenSolaris project[2] introduced new requirements on the
	development process for the components of Solaris which were
	planning on being open-sourced.  One set of requirements revolved
	around the capabilities of the SCM that would be used[3].  After an
	extended evaluation, it was determined that Mercurial would be the
	most appropriate distributed SCM for OpenSolaris projects that
	needed such a tool.

	The version of Mercurial at the time of this writing is 0.9, though
	this project is not specific about the version it intends to
	integrate.  Any architectural changes between 0.9 and future
	versions will be ARCed prior to integration.

3. Architecture

	Mercurial is a distributed SCM, meaning that development on a
	project managed by Mercurial can be done in parallel in different
	repositories scattered across different machines, each containing
	the full history of the project.  As developers wish to create a
	release, one such repository may be designated as the "primary",
	and changes from other repositories merged into it without loss of
	history.  All repositories for a project may be considered peers,
	though convention may assign a heirarchy to them.

	Code sharing can be performed via filesystem access, including NFS,
	http/https, and a byte-stream protocol (normally tunnelled by ssh),
	though the http support is currently restricted to read-only
	operations.  Mercurial doesn't provide any native form of access
	control or authentication, instead relying on the underlying access
	mechanisms (filesystem ACLs, http authentication, etc.) or custom
	extensions to do so.

	Mercurial is written in Python, with a few core pieces (amounting
	to about 5% of the code) written in C for performance.  It is
	released under version 2 of the GPL.

	Mercurial may be extended in two ways.  Extensions may be written
	to augment core functionality -- adding new commands is the primary
	target -- and per-repository or per-user hooks can be written which
	Mercurial will run before or after certain transactions on the
	repository.

	This project depends on PSARC/2005/532[4] to provide Python 2.4
	(and to move Python to its final location in /usr/bin), as well as
	PSARC/2005/555[5] to provide a standard location and mechanism on
	Solaris to find non-core Python extensions.

4. Interfaces

	Exported Interface		Stability	Notes
	------------------		---------	-----
	SUNWmercurial			Committed	Package name
	/usr/bin/hg			Committed	Executable location
	/usr/bin/hgmerge		Committed	Executable location
	hg commandline			Committed	options, subcommands
							and their options
	hg backout			Volatile
	hg clone			Volatile
	hg copy				Volatile
	hg locate			Volatile
	hg manifest			Volatile
	hg merge			Volatile
	hg parents			Volatile
	hg pull				Volatile
	hg rename			Volatile
	hg revert			Volatile
	hg status			Volatile
	hg update			Volatile
	"mercurial"			Committed	Python package name
							for core functionality
	"hgext"				Committed	Python package name
							for extensions
	/etc/mercurial/hgrc		Committed	Path to system config file
	/etc/mercurial/hgrc.d/*.rc	Committed	Pattern of other
							system config files
	$HOME/.hgrc			Committed	Path to user config file
	hgrc contents			Committed	Core commands config only
	<repo>/.hgignore		Committed	List of files to ignore
	HGEDITOR			Committed	Environment variable
	HGMERGE				Committed	Environment variable
	HGRCPATH			Committed	Environment variable
	HGUSER				Committed	Environment variable
	/usr/demo/mercurial		Committed	Place to put contributed
							files from the hg distro
	revlog/index			Committed	File formats
					Private	
	wire protocol			Committed
					Private	

	All programmatic components of Mercurial which appear to be
	interfaces (i.e., class names, variables, methods, etc.) are
	Volatile.  Future project maturity may result in the upgrading of
	the stability of these interfaces.

	Note that some of the hg subcommands are marked as Volatile which
	appear to be (and are) critical to daily operation.  There is some
	work being done here to clean up the UI (such as using -r
	consistently as an argument taking a revision option, which is not
	what, say, "status" and "update" do), and the various "undo"-like
	operations are still undergoing some semantic and name changes.
	The authors expect that this will settle down by version 1.0, at
	which point we can revise the stability levels to Committed.

	Note that despite the declaration of /etc/mercurial as an
	interface, this project does not intend to deliver any files
	beneath it; hence no separate package to do so.

	Imported Interface		Specified in?
	------------------		-------------
	ssh				PSARC/2001/212
	python 2.4			PSARC/2005/532
	vendor-packages			PSARC/2005/555

5. References

	1. http://www.selenic.com/mercurial/
	2. http://www.opensolaris.org/os/
	3. http://www.opensolaris.org/os/community/tools/scm/
	4. PSARC/2005/532 Python migration from /usr/sfw to /usr and upgrade to v2.4.x
	5. PSARC/2005/555 Python "vendor-packages" support