[Monotone-devel] Thoughts about Modules (request for comments)

[Robert White]

So here is five of the most dangerous words in computing:

So I have been thinking...


A lot of people who use CVS don't really use modules.  Some of us do.  I 
am a huge fan of modules because of the need to make stable builds in a 
world where projects need to share sub-projects.  In particular template 
libraries and such.

Monotone doesn't have a modules file, and the way it is designed it 
really _cant_ have one.

But if you decompose the way modules really work in CVS and abstract 
that to the manifest system there is a way to do it.  Essentially you 
need to consider that when you checkout a complicated directory tree 
where sub-trees are deferred into other projects (or segments thereof, 
but we really don't need subsegments).

So in the manifest system we need a way to say "don't descend this 
sub-tree" and we orthogonally need a way to tell the system what we want 
in that tree.  So what we really have is a Bad "Directory, No Donut" 
designator in the Manifest.  So we take "file:" and "dir:" and we add 
"module:".

Now a module entry needs three data.  First is a directory name, because 
just like "dir:" we are describing a sub directory.  Next we need a 
branch name.  Finally we need a revision ID for the manifest the 
contents of the module.

Now the module itself is, in every respect a full and normal checkout of 
a branch.  That is, if we went to that directory and issued various mtn 
commands, there would be no knowledge "in the module" that its directory 
was part of a larger hierarchy.  So a branch in a module directory is 
just like a branch everywhere else.

Now, because we know how to deal with the whole _MTN directory (etc), 
when we are in a branch that contains one or more modules, we can do 
most of our operations (update etc) just by invoking the mtn core 
recursively on the module/branch directories.  Generally you would look 
in the manifest and/or revision files and find all the modules and 
invoke on them before you start really working on your branch-local files.

So when we get through dealing with our modules we invoke on ourselves.

Now there are two basic ways we are going to want to get files out of 
the system.  By branch and by specific version/tag.  This is why we 
store the branch and the revision ID in the module tag in the manifest.  
If you fetch by branch (and update etc) you will get the module sub 
directory by the branch id stored therein.  If you fetch by tag, you 
would first try to fetch the branch by the tag specified (cause it 
_should_ be there since operations are recursive), and if we cannot find 
the branch with the tag, then we get the branch by the revision ID of 
the manifest of the module branch.  And when we are doing the commits 
(etc) we can find the manifest revision id because we know the manifest 
will be in the module_dir/_MTN file.

Storing both data lets us to the full manifest "exact tree" checkout but 
we can still do the head, fork, update

There will probably be some feature flag kind of thing possible so that 
you can "not recurse" into modules etc.

The recursive nature and the simple designations should fit into the 
monotone model very well.

Thoughts?

-- Rob White
Renton, WA.