Adapted monotone's README file and moved it under doc/
Thomas Keller
parent
31e81118dd
commit
0c4846c986
128
README
128
README
|
|
@ -1,128 +0,0 @@
|
|||
monotone implementation notes
|
||||
-----------------------------
|
||||
|
||||
1. general
|
||||
|
||||
This branch contains an implementation of the monotone automation interface.
|
||||
It needs at least monotone version 0.47 (interface version 12.0) or
|
||||
newer. To set up a new project with monotone, all you need to do is
|
||||
to create a new monotone database with
|
||||
|
||||
$ mtn db init -d project.mtn
|
||||
|
||||
in the configured repository path ('mtn_repositories'). To have a really
|
||||
workable setup, this database needs an initial commit on the configured
|
||||
master branch of the project. This can be done easily with
|
||||
|
||||
$ mkdir tmp && touch tmp/remove_me
|
||||
$ mtn import -d project.mtn -b master.branch.name \
|
||||
-m "initial commit" tmp
|
||||
$ rm -rf tmp
|
||||
|
||||
|
||||
2. current state / internals
|
||||
|
||||
The implementation should be fairly stable and fast, though some
|
||||
information, such as individual file sizes or last change information,
|
||||
won't scale well with the tree size. Its expected that the mtn
|
||||
automation interface improves in this area in the future and that
|
||||
these parts can then be rewritten with speed in mind.
|
||||
|
||||
Another area of improvement is the access pattern to the monotone
|
||||
database. While only one process is started per request, the time
|
||||
(and server resource) penalty for this could still be dramatic once
|
||||
many clients try to access the service. Luckily, monotone has an
|
||||
easy way to deliver its stdio protocol for automation usage over the
|
||||
network (mtn au remote_stdio), so the following scenarios are possible:
|
||||
|
||||
a) setup a single mtn server serving one database on a different
|
||||
(faster) server and let the stdio client connect to that
|
||||
|
||||
b) setup usher (available from branch net.venge.monotone.contrib.usher
|
||||
from the official mtn repository on monotone.ca) as proxy in
|
||||
front of several local monotone databases mirroring themselves
|
||||
|
||||
c) like b), but use usher as proxy in front of several other remote
|
||||
monotone databases (forwarding)
|
||||
|
||||
The scenario in a) might be needed anyways for a shared hosting
|
||||
environment, because a database which gets served via netsync cannot
|
||||
be accessed by another local process at the same time (its locked then),
|
||||
so ideally both, the network functionality as well as the indefero
|
||||
browsing functionality should be delivered from one single database
|
||||
per project via netsync.
|
||||
|
||||
The only alternative for this setup is a two-database approach, where one
|
||||
database acts as network node and the other as backend for indefero.
|
||||
The synchronization between these two would then have to happen via
|
||||
standard tools (cron...) or a sync request from one database to the other.
|
||||
|
||||
While the current implementation is ready for the two database approach,
|
||||
some code parts and configuration changes have to happen for the remote
|
||||
stdio usage. Bascially this is replacing the initial call to
|
||||
|
||||
mtn -d project.mtn au stdio (Monotone.php, around line 74)
|
||||
|
||||
with
|
||||
|
||||
mtn au remote_stdio HOSTNAME
|
||||
|
||||
which could be made configurable in conf/idf.php. But again, this heavily
|
||||
depends on the exact anticipated server setup.
|
||||
|
||||
To scale things up a bit, multiple projects should of course use
|
||||
separated databases. The main reason for that is that while read access
|
||||
can be granted on a branch level, write access gives total write
|
||||
possibilities on the whole database. One approach would be to start
|
||||
one serve process for each database, but the obvious downside here is
|
||||
that each of those processes would need to get bound to another
|
||||
(non-standard) port making it hard for users to "just clone" the
|
||||
project sources without knowing the exact port.
|
||||
|
||||
Usher comes to the rescue here as well. It has three ways
|
||||
to recognize the request for a particular database:
|
||||
|
||||
a) by looking at the requested host name (similar to SNI for Apache)
|
||||
|
||||
b) by evaluating the requested branch pattern
|
||||
|
||||
c) by evaluating the path part from an mtn:// uri (new in mtn 0.48)
|
||||
|
||||
The best way is probably to configure it with c) - instead of pulling
|
||||
a project like this
|
||||
|
||||
$ mtn pull hostname branchname
|
||||
|
||||
a user uses the URI syntax (which will, btw. be the default from
|
||||
mtn 0.99 onwards):
|
||||
|
||||
$ mtn pull mtn://hostname/database?branchname
|
||||
|
||||
Here, the "/database" part is used by usher to determine which backend
|
||||
database should be used for the network action. The "clone" command
|
||||
will also support this mtn:// uri syntax, but this didn't made it into
|
||||
0.48, but will be available from 0.99 and later.
|
||||
|
||||
|
||||
3. indefero critique:
|
||||
|
||||
It was not always 100% clear what some of the abstract SCM API method
|
||||
wanted in return. While it helped a lot to have prior art in form of the
|
||||
SVN and git implementation, the documentation of the abstract IDF_Scm
|
||||
should probably still be improved.
|
||||
|
||||
Since branch and tag names can be of arbitrary size, it was not possible
|
||||
to display them completely in the default layout. This might be a problem
|
||||
in other SCMs as well, in particular for the monotone implementation I
|
||||
introduced a special filter, called "IDF_Views_Source_ShortenString".
|
||||
|
||||
The API methods getPathInfo() and getTree() return similar VCS "objects"
|
||||
which unfortunately do not have a well-defined structure - this should
|
||||
probably addressed in future indefero releases.
|
||||
|
||||
While the returned objects from getTree() contain all the needed
|
||||
information, indefero doesn't seem to use them to sort the output
|
||||
f.e. alphabetically or in such a way that directories are outputted
|
||||
before files. It was unclear if the SCM implementor should do this
|
||||
task or not and what the admired default sorting should be.
|
||||
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# monotone implementation notes
|
||||
|
||||
## general
|
||||
|
||||
This version of indefero contains an implementation of the monotone
|
||||
automation interface. It needs at least monotone version 0.47
|
||||
(interface version 12.0) or newer, but as development continues, its
|
||||
likely that this dependency has to be raised.
|
||||
|
||||
To set up a new IDF project with monotone quickly, all you need to do
|
||||
is to create a new monotone database with
|
||||
|
||||
$ mtn db init -d project.mtn
|
||||
|
||||
in the configured repository path `$cfg['mtn_repositories']` and
|
||||
configure `$cfg['mtn_db_access']` to "local".
|
||||
|
||||
To have a really workable setup, this database needs an initial commit
|
||||
on the configured master branch of the project. This can be done easily
|
||||
with
|
||||
|
||||
$ mkdir tmp && touch tmp/remove_me
|
||||
$ mtn import -d project.mtn -b master.branch.name \
|
||||
-m "initial commit" tmp
|
||||
$ rm -rf tmp
|
||||
|
||||
Its expected that more scripts arrive soon to automate this and other
|
||||
tasks in the future for (multi)forge setups.
|
||||
|
||||
## current state / internals
|
||||
|
||||
The implementation should be fairly stable and fast, though some
|
||||
information, such as individual file sizes or last change information,
|
||||
won't scale well with the tree size. Its expected that the mtn
|
||||
automation interface improves in this area in the future and that
|
||||
these parts can then be rewritten with speed in mind.
|
||||
|
||||
As the idf.conf-dist explains more in detail, different access patterns
|
||||
are possible to retrieve changeset data from monotone. Please refer
|
||||
to the documentation there for more information.
|
||||
|
||||
## indefero critique:
|
||||
|
||||
It was not always 100% clear what some of the abstract SCM API method
|
||||
wanted in return. While it helped a lot to have prior art in form of the
|
||||
SVN and git implementation, the documentation of the abstract IDF_Scm
|
||||
should probably still be improved.
|
||||
|
||||
Since branch and tag names can be of arbitrary size, it was not possible
|
||||
to display them completely in the default layout. This might be a problem
|
||||
in other SCMs as well, in particular for the monotone implementation I
|
||||
introduced a special filter, called "IDF_Views_Source_ShortenString".
|
||||
|
||||
The API methods getPathInfo() and getTree() return similar VCS "objects"
|
||||
which unfortunately do not have a well-defined structure - this should
|
||||
probably addressed in future indefero releases.
|
||||
|
||||
While the returned objects from getTree() contain all the needed
|
||||
information, indefero doesn't seem to use them to sort the output
|
||||
f.e. alphabetically or in such a way that directories are outputted
|
||||
before files. It was unclear if the SCM implementor should do this
|
||||
task or not and what the admired default sorting should be.
|
||||
|
||||
Loading…
Reference in New Issue