Re: [Monotone-devel] Best practice using monotone

[jack-monotone]

On Wed, Aug 23, 2006 at 09:30:33PM +0100, Andy Jones wrote:

> Can anyone point me to a discussion on best practice using Monotone?
 
...

> I suppose it's correct that the manual doesn't go into these things - it
> should tell you how monotone works, not how to use it.  But maybe there needs
> to be something?

I agree, and I've been meaning to contribute mine. 

Here's a start. Comments welcome. Somewhere on my todo list is to create a
patch to the manual:

=== Branch Naming

    Many things have been suggested in the wiki, but nothing seems to have
gained sufficient momentum to replace the inverted FQDN + branch
(net.venge.monotone) approach. 

    Monotone doesn't care what branches are called, and you can rename branches
later on. 

=== Creating Branches

    If you want to create a new branch, the most intuitive way (that I've
found) is to commit your changes with --branch=<new_branch> .

=== Vendor Branch Pattern

    If you are working on a project that has been partitioned, give each
partition a branch. A partition could be upstream code. 

    Then merge_into_dir each partition into your project. Use explicit_merge to
integrate releases. If you have made some local changes that didn't make sense
to push back upstream, monotone will try to maintain them. 

    For example, let's say your project 'com.example.foo' uses sqlite. Instead
of dumping sqlite into /sqlite of your project and committing it, give sqlite
into a branch of it's own. Perhaps 'org.sqlite' is a good name. You can use
this branch to track the sqlite development: perhaps only tracking releases,
perhaps pulling from the sqlite VCS using tailor or some other magic.  Tag
releases that you are interested in with meaningful tags 'sqlite-3.2.5'. 

    Now, merge_into_dir org.sqlite com.example.foo sqlite. 

    You can use the org.sqlite branch to play around with sqlite, and when you
find a new version that you want to try, you can use explicit_merge (or
propagate) to bring it into com.example.foo. 
    
=== Release Branch Pattern

    You are acting as an integrator and need a mechanism to managed delivies to
customers. This delivery could come from several vendor branches (see above).
This delivery could have all of the files rearranged. 

    Create a working branch 'example.com.foo' using the Vendor Branch Pattern.
Pick the revisions of the sub-branches that you want to deliver, and merge them
into your work branch. 

    Create a branch off of your work branch that you will deliver
'example.com.foo.deliverables' (a simple way of doing this is to commit with
the --branch option)

    In the 'example.com.foo.delerables' branch, drop all of the files and
directories that you don't want to deliver. Rename the files that you do wish
to deliver as you see fit. 

    When it is time for a new release, do an explicit merge from the
sub-branches to your 'example.com.foo.work' branch, run your integration
scripts, and then propagate from 'example.com.foo' to
'example.com.foo.deliverables'. Monotone will remember and understand all of
your deletes and renames and propagate changes through them. 

    NOTES:

        - if one of the sub-branches added a file to a directory that was
          dropped in the 'example.com.foo.delivebles' branch, then you'll get a
non merge conflict when you do the propagate. These are a pain to solve, at
least until the workspace merge is integrated into mainline monotone. 

=== Use separate databases for working and serving

    At some point you'll want to share your work with others, and set up a sync
server. You can run a 'mtn serve' off of the same database that you
check all of your changes into. This will work, but it has problems:

    - when you are working, and commiting code, monotone locks the database.
      The monotone server then can't serve anything anymore. 

    It is better to have a separate database to run monotone serve off of, and
sync to it locally. 

=== Use One branch per db for servers (and usher)

    If you have a lot of big branches (maybe you need to version control a
library of some sort), you can get a large db file. sqlite and monotone are
paranoid about data integrity, but it is possible that a hardware failure
during an operation can hose parts of the database. 

    It is better to have a db file for each branch, and use usher
(net.monotone.contrib.usher) to proxy connections to each branch. 

=== Run "db check regularly"

    Monotone is careful about data integrity, but there are limits to what can
be reasonably protected against in software. 
    
    Running 'db check' on your databases on a regular basis is a good idea. 'db
check' does a careful check of the consistency of the database. 

    This is especially important for databases that are being served. 

=== Make small commits, often

    Don't group many changes together into a single commit. Do a commit for
each logical change. This makes it easier for others to "pluck" or cherry pick
only the changes they are interested in. 

    For example, commit bug fixes and feature enhancements separately. 

--Jack


--
Jack (John) Cummings                           http://mudshark.org/
PGP fingerprint: F18B 13A3 6D06 D48A 598D  42EA 3D53 BDC8 7917 F802

pgpBuMBey7Sr0.pgp
Description: PGP signature