Using Mercurial With the DTN Source Code

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

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.hg.sourceforge.net/hgweb/dtn.

Specifically, to clone the DTN2 repository: 

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

DTN2 also requires oasys. You can get it through: 

   hg clone http://dtn.hg.sourceforge.net/hgweb/dtn/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.

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 2009-12-07 18:23:47 by alexmcmahon)