Using Mercurial With the DTN Source Code

The main DTN reference implemention source code is now maintained in Mercurial and is hosted on SourceForge.

Note: We are currently in the process of migrating hosting for the code and release management to sourceforge. Some of the information below may be inaccurate during the transition. Email Michael Demmer if there are problems with the information.

This page briefly describes how to access the DTN reference implementation and related source trees. For more information on how to use Mercurial, there are several external sources with documentation: UnderstandingMercurial Tutorial hgbook

Unlike CVS, Mercurial is a distributed version control system, which means that source code revisions can be shared between developers without necessarily accessing a central repository. The DTNRG group maintains an "official" repository for the latest version and releases of the DTN2 reference implementation on code.dtnrg.org.

Accessing the repository

HTTP access

You can both browse the repository and clone it (i.e. get a local repository and working directory) at http://dtn.sourceforge.net/hg.

Specifically, to clone the DTN2 repository: 

  hg clone http://dtn.sourceforge.net/hg/DTN2

DTN2 also requires oasys. Eventually we may distribute prebuilt versions of oasys, but for now you can get it through: 

   hg clone http://dtn.sourceforge.net/hg/oasys

Cloning using SSH

Contributing directly to the repository requires users to be a registered developer for the 'dtn' sourceforge project. After signing up for a sourceforge account, contact one of the project administrators listed on the SourceForge DTN Project Page to be added to the project.

You will also need to register an SSH key for shell access. See http://alexandria.wiki.sourceforge.net/SSH+Key+Generation.

Once you can successfully log in to shell.sf.net using ssh, you need to edit your ~/.bashrc file and add the following lines to be able to use mercurial properly: 

   export PATH=$PATH:/home/groups/d/dt/dtn/mercurial
   umask 0002

Once that is all set up, to clone the DTN2 and oasys repositories, use: 

   hg clone ssh://<username>@shell.sf.net//home/groups/d/dt/dtn/hg-repository/DTN2
   hg clone ssh://<username>@shell.sf.net//home/groups/d/dt/dtn/hg-repository/oasys

Note the double slash before the data path, and make sure to replace [username@] with your appropriate username.

Updating to the current version

To update to the current set of changes requires two steps, first to pull changes into your local repository, then update your local snapshot to those changes: 

  hg pull
  hg update

You can do both these steps in one by using: 

   hg pull -u

For more information, see the mercurial documentation.

Committing a change

In mercurial, commits are all first made to a local repository, and can then be shared with another repository (e.g. the master repository) using a variety of methods.

Thus anyone can commit local changes to their locally cloned repository using: 

   hg commit

It's useful to first set up a ~/.hgrc file in your home directory containing your name and email address, for example: 

    [ui]
    username = Developer T Nobody <dtn@nowhere.com>

Once you've made local commits, you can still update to incorporate changes from the main tree, but you'll need to manage multiple local branches. See the mercurial documentation for more explanation.

Contributing patches

If you have read/write access over ssh and have cloned the repository using the above-mentioned commands, then any changes you have made locally can be shared with the master repository using: 

   hg push

If instead you have cloned the repository using http, but still have patches that you want to contribute back to the main source tree, then first do a local commit as described above. Then export this changeset using: 

   hg export REV

Where REV is the revision number of your commit. Capture the output from the command into a file and email it as an attachment to dtn-users@mailman.dtnrg.org.

Using the exported changeset (as opposed to a simple patch) is preferable because the changeset will include your name, email, and checkin comment which will be put into the mercurial change log.

You can do this in bulk for multiple commits using: 

   hg export -o mypatch-%n REV1 [REV2] [REV3]

This will create N files, one for each revision, named "mypatch-1", "mypatch-2", etc. Run 'hg help export' for more information.

Differences from CVS

Fundamentally, mercurial is a distributed VC system instead of a centralized one, so there are a large number of differences that are better described elsewhere.

Some more specific minor differences include:

UsingMercurial (last edited 2008-08-12 18:20:05 by demmer)