modules/versioncontrol_hg/README.txt

VERSION CONTROL: MERCURIAL
--------------------------

Author: Edward Z. Yang (ezyang, http://drupal.org/user/211688)

Mercurial is a distributed revision control system written in Python.
This module implements Mercurial's API for the Version Control API.

STATUS
------

The following items have been completed:

- Core Mercurial PHP wrapper functions
- Install/uninstall hooks
- Database schema
- Module information hook
- Log to database adapter
- Works with commit log
- Parents are now *really* recorded and reconstituted properly
- Branches are logged
- Refactoring to process one log entry at a time globally
- Tags logging / Tag tracking

TODO EXTRA!
-----------

These todo items aren't strictly necessary to complete the GHOP task
but are things I'd like to do some time.

- Documentation on which order one should implement things for a
  versioncontrol backend (based on this experience)
- Formalize any redundancies, determine which ones should be kept for
  performance and which ones should be scrapped in favor of JOINS.
- Make log parsing use low memory
- Figure out how to import a richer hg repository for testing

TODO FOR CRAZY PEOPLE
---------------------

Enough said.

- Implement xhg hook scripts
- Develop a repository administration interface for creating new
  repositories for new projects, etc.

DESIGN DECISIONS
----------------

The versioncontrol module is reasonably RCS agnostic, but its documentation
is greatly lacking in terms of some of the most important implementation
details and idioms; the fact that CVS is the only reference implementation
available complicates things greatly.

We chose to retain the basic setup of CVS with regards to inserting log
data in the database, and then spitting it out for further processing
(facilities for this are explicitly provided using auto-commit). However,
we redesigned many of the tables (and dropped several) to ensure a cleaner
map to Mercurial's features. The most important thing to remember is that
INSTANTIATING THE IN-MEMORY STRUCTURE FROM THE DATABASE SHOULD TAKE AS
LITTLE CODE AS POSSIBLE. Thus, all data is saved in the form that
versioncontrol demands, and then allowances are made for Mercurial, and
extra fields added for full retention. The parallel, at times competing,
goal is: DUPLICATE INFORMATION AS LITTLE AS POSSIBLE (except when
necessary for performance). Thus, we omitted many fields when they
could be appropriately determined from a foreign key association.

I have carefully reviewed every bit of code from CVS that influenced
design decisions here, and diverged whenever differences between the
two RCS's were great enough that it was merited. One major change that
I'd like to see merged back to CVS is the use of a PHP function wrapper
backend to hide the tangly mess of command line calls, and perhaps
allow PHP to use the native function library.

TAGS
----

Tags in Mercurial are handled in an interesting manner: the .hgtags
file contains any of the recognized tags in a repository at any point
in time. Thus, changes to it must be manually detected and translated
into tag operations. We have chosen to only report adds or deletes; it
is possible that the same revision have multiple tags, so there are
ambiguous cases if we try to figure out renames.

Updating the "current" tag state is done by truncating the tags table
for that repository, and then repopulating it with the contents of
.hgtags.

XHG - Commit Scripts
--------------------

If you want versioncontrol_hg to be instantly updated after you push
changes to the master server, you can set up a changegroup hook in
hgrc to run Drupal's cron:

[hooks]
changegroup = php /path/to/drupal/cron.php

We have decided specifically not to offer our own post-commit script,
as running cron.php directly is simpler. If, for whatever reason, you
don't want cron run whenever a changegroup is pushed to Mercurial, you
can make a quick post-commit script:

<?php
include_once '/path/to/drupal/includes/bootstrap.inc';
drupal_bootstrap(DRUPAL_BOOTSTRAP_FULL);
versioncontrol_hg_cron();
?>

KNOWN ISSUES
------------

Major issues:

- What's up with versioncontrol_hg_get_current_item_tag()?

Minor issues:

- 'file_copies' as per the Mercurial output doesn't ever seem to be
  triggered; the implementation for this case is accordingly patchy,
  especially use of the 'modified' flag. More research is necessary in
  this respect. For now, this should be harmless enough.

Possible upstream issues:

- There is a lot of functionality that feels like it would be better
  placed in versioncontrol itself; namely [versioncontrol_vcs]_get_directory_item(),
  [versioncontrol_vcs]_get_commit_branches, and large portions of
  [versioncontrol_vcs]_commit (which should have a good deal of the
  commit action tomfoolery auto-updated by versioncontrol.)

- There's a lot of docblock duplication, which worries me. We ought to be
  able to say hook_[hookname] and defer the documenting to versioncontrol
  itself.

- Commit log should link to our previous revisions, i.e. (modified: <a href="...">234dab3...</a>)

- Deleted files can have source items too, but what values are appropriate?
  The last changeset on the file before it was deleted? The changeset
  of the deletion of the file in another branch? We currently do both,
  although the latter is slightly iffy, but certainly useful info. Commit
  log currently truncates source items to the first item, which is the original,
  so there are no problems.

- In fact, commit log truncates all source items to one entry. Scandalous!

- Using SHA-1 hashes for revision is really ugly; maybe we should use the
  non-portable revision numbers? (Ideally, compact nodeids would be
  used, but we need a way to calculate them on the fly due to the
  risk of collisions.) This would be an extension to commit log.

- Using email as account name results in commit log displaying the
  email to the world. It is unknown if, when we give versioncontrol
  the ability to lookup uids based on emails, these emails will be
  suppressed from public view.

- versioncontrol_hg_ensure_branch() automatically creates a branch if
  it doesn't exist; it might be helpful (esp. for VCSs that use repository
  wide branches) if there was a hook attached to it.

STRUCTURE
---------

hg/            Generic code for interfacing with Mercurial via command line
  templates/   These are our custom templates to minimize necessary log parsing
tests/         SimpleTest unit tests for hg/
  db/          A multitude of useful *.sql and *.dbquery files for testing
               and resetting the database.
1	VERSION CONTROL: MERCURIAL
2	--------------------------
3
4	Author: Edward Z. Yang (ezyang, http://drupal.org/user/211688)
5
6	Mercurial is a distributed revision control system written in Python.
7	This module implements Mercurial's API for the Version Control API.
8
9	STATUS
10	------
11
12	The following items have been completed:
13
14	- Core Mercurial PHP wrapper functions
15	- Install/uninstall hooks
16	- Database schema
17	- Module information hook
18	- Log to database adapter
19	- Works with commit log
20	- Parents are now really recorded and reconstituted properly
21	- Branches are logged
22	- Refactoring to process one log entry at a time globally
23	- Tags logging / Tag tracking
24
25	TODO EXTRA!
26	-----------
27
28	These todo items aren't strictly necessary to complete the GHOP task
29	but are things I'd like to do some time.
30
31	- Documentation on which order one should implement things for a
32	versioncontrol backend (based on this experience)
33	- Formalize any redundancies, determine which ones should be kept for
34	performance and which ones should be scrapped in favor of JOINS.
35	- Make log parsing use low memory
36	- Figure out how to import a richer hg repository for testing
37
38	TODO FOR CRAZY PEOPLE
39	---------------------
40
41	Enough said.
42
43	- Implement xhg hook scripts
44	- Develop a repository administration interface for creating new
45	repositories for new projects, etc.
46
47	DESIGN DECISIONS
48	----------------
49
50	The versioncontrol module is reasonably RCS agnostic, but its documentation
51	is greatly lacking in terms of some of the most important implementation
52	details and idioms; the fact that CVS is the only reference implementation
53	available complicates things greatly.
54
55	We chose to retain the basic setup of CVS with regards to inserting log
56	data in the database, and then spitting it out for further processing
57	(facilities for this are explicitly provided using auto-commit). However,
58	we redesigned many of the tables (and dropped several) to ensure a cleaner
59	map to Mercurial's features. The most important thing to remember is that
60	INSTANTIATING THE IN-MEMORY STRUCTURE FROM THE DATABASE SHOULD TAKE AS
61	LITTLE CODE AS POSSIBLE. Thus, all data is saved in the form that
62	versioncontrol demands, and then allowances are made for Mercurial, and
63	extra fields added for full retention. The parallel, at times competing,
64	goal is: DUPLICATE INFORMATION AS LITTLE AS POSSIBLE (except when
65	necessary for performance). Thus, we omitted many fields when they
66	could be appropriately determined from a foreign key association.
67
68	I have carefully reviewed every bit of code from CVS that influenced
69	design decisions here, and diverged whenever differences between the
70	two RCS's were great enough that it was merited. One major change that
71	I'd like to see merged back to CVS is the use of a PHP function wrapper
72	backend to hide the tangly mess of command line calls, and perhaps
73	allow PHP to use the native function library.
74
75	TAGS
76	----
77
78	Tags in Mercurial are handled in an interesting manner: the .hgtags
79	file contains any of the recognized tags in a repository at any point
80	in time. Thus, changes to it must be manually detected and translated
81	into tag operations. We have chosen to only report adds or deletes; it
82	is possible that the same revision have multiple tags, so there are
83	ambiguous cases if we try to figure out renames.
84
85	Updating the "current" tag state is done by truncating the tags table
86	for that repository, and then repopulating it with the contents of
87	.hgtags.
88
89	XHG - Commit Scripts
90	--------------------
91
92	If you want versioncontrol_hg to be instantly updated after you push
93	changes to the master server, you can set up a changegroup hook in
94	hgrc to run Drupal's cron:
95
96	[hooks]
97	changegroup = php /path/to/drupal/cron.php
98
99	We have decided specifically not to offer our own post-commit script,
100	as running cron.php directly is simpler. If, for whatever reason, you
101	don't want cron run whenever a changegroup is pushed to Mercurial, you
102	can make a quick post-commit script:
103
104	<?php
105	include_once '/path/to/drupal/includes/bootstrap.inc';
106	drupal_bootstrap(DRUPAL_BOOTSTRAP_FULL);
107	versioncontrol_hg_cron();
108	?>
109
110	KNOWN ISSUES
111	------------
112
113	Major issues:
114
115	- What's up with versioncontrol_hg_get_current_item_tag()?
116
117	Minor issues:
118
119	- 'file_copies' as per the Mercurial output doesn't ever seem to be
120	triggered; the implementation for this case is accordingly patchy,
121	especially use of the 'modified' flag. More research is necessary in
122	this respect. For now, this should be harmless enough.
123
124	Possible upstream issues:
125
126	- There is a lot of functionality that feels like it would be better
127	placed in versioncontrol itself; namely [versioncontrol_vcs]_get_directory_item(),
128	[versioncontrol_vcs]_get_commit_branches, and large portions of
129	[versioncontrol_vcs]_commit (which should have a good deal of the
130	commit action tomfoolery auto-updated by versioncontrol.)
131
132	- There's a lot of docblock duplication, which worries me. We ought to be
133	able to say hook_[hookname] and defer the documenting to versioncontrol
134	itself.
135
136	- Commit log should link to our previous revisions, i.e. (modified: <a href="...">234dab3...</a>)
137
138	- Deleted files can have source items too, but what values are appropriate?
139	The last changeset on the file before it was deleted? The changeset
140	of the deletion of the file in another branch? We currently do both,
141	although the latter is slightly iffy, but certainly useful info. Commit
142	log currently truncates source items to the first item, which is the original,
143	so there are no problems.
144
145	- In fact, commit log truncates all source items to one entry. Scandalous!
146
147	- Using SHA-1 hashes for revision is really ugly; maybe we should use the
148	non-portable revision numbers? (Ideally, compact nodeids would be
149	used, but we need a way to calculate them on the fly due to the
150	risk of collisions.) This would be an extension to commit log.
151
152	- Using email as account name results in commit log displaying the
153	email to the world. It is unknown if, when we give versioncontrol
154	the ability to lookup uids based on emails, these emails will be
155	suppressed from public view.
156
157	- versioncontrol_hg_ensure_branch() automatically creates a branch if
158	it doesn't exist; it might be helpful (esp. for VCSs that use repository
159	wide branches) if there was a hook attached to it.
160
161	STRUCTURE
162	---------
163
164	hg/ Generic code for interfacing with Mercurial via command line
165	templates/ These are our custom templates to minimize necessary log parsing
166	tests/ SimpleTest unit tests for hg/
167	db/ A multitude of useful .sql and .dbquery files for testing
168	and resetting the database.