xarigami dev - starting with monotone

Posted by: Jo on January 20, 2009 |  Updated: December 30, 2011 01:45 PM

checkout and tracking of xarigami code changes


At xarigami we use Monotone to manage changes that are made in the code. Monotone is a free, open source cross platform application licenced under the Gnu GPL. It enables us to maintain a history of all the revisions made to the xarigami code, and information about those changes.  All of this revision information managed by Monotone is stored in a database (sqlite).

At xarigami we have a Monotone database for xarigami core projects, a database for xarigami modules and addons, and another database for xarigami themes. These main 'reference' databases for xarigami code are stored on one of xarigami's servers. Each xarigami project, either a module, theme, or core scenario, is stored in a 'branch' in the relevant database.

What can you do with Monotone and xarigami code?

To submit changes directly to the xarigami core code, modules or themes you must use Monotone and have at least one database containing the xarigami branch you want to work on or track. Everyone can have their own database of xarigami code, and easily share changes with each other. This is why it is called a distributed versioning system.

You can use Monotone to do some very handy things such as keep up to date with development at xarigami as it allows you to grab the latest code from a project branch, whenever you want it, including the revisions and all the information related to those revisions. You can also use it to setup a whole xarigami website on disk and keep it easily updated, or check to see if you accidentally (or someone else) made changes to any files in your site.

Access to xarigami code repositories via Monotone is provided to those that have contributed patches that have been applied to xarigami code base, and want to continue to be involved in xarigami development.

What information does this reference document cover?

This reference document provides a simple outline of steps to:

  1. Setup your xarigami monotone databases
  2. Create your monotone keypair
  3. Pull code branches from the xarigami reference database
  4. Checkout the code to view, work on code, or run a site
  5. Update to the latest xarigami code with Monotone

Make sure you have downloaded Monotone for your operating system and installed it, and it is working. There is a comprehensive document on Monotone for those that wish to read it.

1. Setup your xarigami monotone databases

You may want to store all the xarigami core, module and theme code branches in one database. Altenatively you may find it easier to have one database for core project branches, one for module branches, and one for themes branches, like the Xarigami reference databases. It is up to you, and you can name them in any way you want but having it as xarigamicore.db, xarigamimodules, or xarigami.db are good choices.

  • Decide in what directory you are going to store your databases on your server or local computer.
  • Create a new database (do not include square brackets in the command)
    mtn db init --db=[databasename]
  • If you list the contents of the directory you should now see your new database. Create as many as you need.

2. Create a unique monotone keypair

You will need to create a monotone 'key' to access the xarigami monotone databases.

A monotone key uniquely identifies you and is also used to gain access to monotone databases that have restricted access. A monotone key is actually a pair of keys  - a public key and a private key part.

  • Generate a keypair using any of your databases - the 'keyid' is an email address, real or a dummy one eg
    mtn -d [databasename] genkey somename@somemail.com

    You will also be prompted for a pass phrase when you generate your key. Don't forget your keyid and password phrase!

  • Export your public key from the database - [keyid] is the email you used
    mtn -d [databasename] pubkey [keyid]> pubkey.txt
  • Email your public key file (pubkey.txt)  and keyid to:
    talktous (AT) 2skies (DOT) com

  • Wait for confirmation of your access to the xarigami code repositories

3. Pull code branches from the xarigami reference database

Now you have access, you can pull in the xarigami code branches to your own local databse(s). To do this you need to know the branch you want and database it resides in. For xarigami here are the databases and the commands to access the branches in those databases (do not include square brackets).

  • Xarigami Core
    The com.2skies.xarigami.core branch is available. For those that have commit access to xarigami repositories you will also need the com.2skies.xarigami.qa.tests branch (more about that later).
    mtn -d [yourdatabasepath/name] pull dev.2skies.com com.2skies.xarigami.core -k [yourkeyid]
  • Xarigami Modules
    For each module you require, you will need to pull the relevant branch to your database
    mtn -d [yourdatabasepath/name] pull dev.2skies.com:15000 com.2skies.xarigami.modules.[modulename] -k [yourkeyid]
  • Xarigami Themes
    For each theme you require, you will need to pull the relevant branch to your database
    mtn -d [yourdatabasepath/name] pull dev.2skies.com:16000 com.2skies.xarigami.themes.[themename] -k [yourkeyid]

You can list the branches you have in any of your databases using the following command:

mtn -d [yourdatabasepath/name] ls branches

4. Checkout and update code to view, work on code, or run a xarigami site

Once you have pulled the branches into your own database, you can then check out 'monotone working copies' of those branches into a directory on your server or local computer.

You can checkout a 'monotone working copy' of any branch into any directory and work on it, or view changes and history. However in this example we will demonstrate how to checkout the core and module branches in a structure to run a xarigami site from those monotone working directories.

  • Decide where you want to checkout your 'core' monotone working directory. It must be to a directory that doesn't already exist. In our example we will checkout to a 'virtual host' directory called 'www.mysite.com' from the parent directory:
    mtn -d [yourdatabasepath/name] co -b com.2skies.xarigami.core www.mysite.com
  • List the directory contents of the directory of www.mysite.com and you will see a directory structure something like:
    _MTNhtml    includes    modules    themes    xaradodb    varsamplesteststools

    The _MTN directory signifies all the files from the current directory down are managed for revision by Monotone. The _MTN is a special directory that contains information used to keep track of your monotone working directory revisions.

    The 'html' directory is where your site document directory should be located if you were to run a site from this core monotone working copy checkout.

  • Checkout your xarigami modules from your monotone databse into the html/modules directory in a directory with the name of the module. Assuming the modules directory is your the current directory:
    mtn -d [yourdatabasepath/name] co -b com.2skies.xarigami.modules.articles articles

    You should now find a new monotone working directory called 'articles' in your modules directory, with all the article module code in it. You will also see a _MTN directory in the 'articles' directory signifying that all files in this directory tree are now under Monotone revision control.

    Checkout the other modules you require for your site, or those that you want to review or work on. Notice how these non-core modules can easily be nested inside the modules directory which is itself part of the xarigami core monotone working directory structure.

You can now use your monotone working copy for Xarigami Core, and for individual Xarigami Modules to review the code, the history of changes, and even diffs between revisions. Later, if you want to change code and commit it to the Xarigami repository you can do that here as well in your working copies. 

When you want to view information about changes in xarigami core, or a xarigami module, make sure you are in a directory in that core or module working copy and issue a command. Here are some common and useful ones, including how to check if you accidentally changed a file (or someone else did!).

  • List the last 5 revisions to core - brief mode
    mtn -d [yourdatabasepath/name] log --last=5 --brief
    o     772f0d02d91e8f2810818d7db0b97f0c36cb6654 icedlava@2skies.com|    2009-01-19T16:48:56 com.2skies.xarigami.coreo |   abb2a8118b56228d38dc62dbd9073ab1ca874888 icedlava@2skies.com| |   2009-01-19T13:41:10 com.2skies.xarigami.core| o   de6fc6c0573f260b043f8460809ed3607f3109f8 lakys-xarigami@lakeworks.com|/    2009-01-19T16:03:50 com.2skies.xarigami.coreo   ec0f1349ffc0dcf0f2e60900947afd0d90b8c006 icedlava@2skies.com|   2009-01-18T18:45:41 com.2skies.xarigami.coreo   cd498c3fa9cbe6065d2beb8172c47d0d2e3dd148 icedlava@2skies.com
  • List the last revision in Smilies module - normal mode
    mtn -d [yourdatabasepath/name] log --last=1
    |   Revision: f809c869260e0a2739a64b6d5f49fb941d52650c|   Ancestor: f3a41faa6387870c2e432acd3476d9d9044878b5|   Author: icedlava@2skies.com|   Date: 2008-12-16T03:32:54|   Branch: com.2skies.xarigami.modules.smilies|   |   Modified files:|           xartemplates/user-formdisplay.xd xaruserapi/countitems.php|           xaruserapi/get.php xaruserapi/getall.php|           xaruserapi/transform.php|   |   ChangeLog: |   |   Remove return by ref errors
  • List the last 5 revisions in core - no graph and no merges
    abb2a8118b56228d38dc62dbd9073ab1ca874888 icedlava@2skies.com 2009-01-19T13:41:10 com.2skies.xarigami.corede6fc6c0573f260b043f8460809ed3607f3109f8 lakys-xarigami@lakeworks.com 2009-01-19T16:03:50 com.2skies.xarigami.coreec0f1349ffc0dcf0f2e60900947afd0d90b8c006 icedlava@2skies.com 2009-01-18T18:45:41 com.2skies.xarigami.corecd498c3fa9cbe6065d2beb8172c47d0d2e3dd148 icedlava@2skies.com 2009-01-17T10:30:17 com.2skies.xarigami.core79aadd59e286f7f3c9556cfb66eda738a93fa0a5 icedlava@2skies.com 2009-01-16T18:32:35 com.2skies.xarigami.core 
  • List the last revision in articles with diffs
    mtn -d [yourdatabasepath/name] log --last=1 --diffs
      Revision: 7a335d447fe8b73e92a4094fab848d71d7d0b53d
    |   Ancestor: dd4f96fbfd7890636462339bc39171ae222929fe
    |   Author: icedlava@2skies.com
    |   Date: 2009-01-18T16:26:45
    |   Branch: com.2skies.xarigami.modules.articles
    |   Modified files:
    |           xaruserapi/getstates.php 
    |   ChangeLog: 
    |   Bug 6300 add draft status. Basically adds a new tab. Allows allocation of article to a Draft 
    |   as distinct from Submitted.
    |      ============================================================
    |   --- xaruserapi/getstates.php	b33f6a18705ddfe318920f6c964bb84813118749
    |   +++ xaruserapi/getstates.php	6facf4350e94d55d1e6d158042f5d20a7fdb0631
    |   @@ -3,7 +3,7 @@
    |     * Articles module
    |     *
    |     * @package modules
    |   - * @copyright (C) 2002-2007 The Digital Development Foundation
    |   + * @copyright (C) 2002-2009 The Digital Development Foundation
    |     * @license GPL {@link http://www.gnu.org/licenses/gpl.html}
    |     * @link http://www.xaraya.com
    |     *
    |   @@ -23,7 +23,7 @@ function articles_userapi_getstates()
    |                     1 => xarML('Rejected'),
    |                     2 => xarML('Approved'),
    |                     3 => xarML('Frontpage'),
    |   -           //    4 => xarML('Unknown')
    |   +                 4 => xarML('Draft')
    |                     );
    |    }
    |    ?> 
  • Check to see if any files have been changed in your xarbb module working copy
    mtn -d [yourdatabasepath/name] ls changed

5. Update to the latest code with Monotone

Now you have created your monotone working copies, you can update these with the latest xarigami code at any time. This is a good way to update a site or modules in your site.

  • Pull down the latest code from the Xarigami reference database to your local database
    mtn -d [yourdatabasepath/name] pull dev.2skies.com com.2skies.xarigami.core -k [yourkeyid] 
  • Now change directory to, in this case, your core monotone working copy (any directory in the tree) and tell monotone to update this working copy to the latest code you have just pulled down:
    mtn-d [yourdatabasepath/name] update 

If there are any new changes, or new files, they will be applied to the relevant files and directories in your current monotone working copy, in this case any of the xarigami core files.

Please note that issuing a monotone update command will not automatically overwrite any changes you have made in your monotone working copy.


For more information on making changes to code and commiting this to the Xarigami code repository please see 'Xarigami dev - commiting code'.

Related project :

xarigami core

« prev     next»

useful? share it.