Projects - Developing With Arch

This document covers the basic routine for committing patches with Arch. The use of Emacs is emphasized.

[ Top: Arch Tutorial ]
[ Previous is Part 1: Getting Started With Arch ]
[ This is Part 2: Developing With Arch ]
[ Next is Part 3: Cooperation and Arch ]

Getting an Arch helper for Emacs

I recommend using DVC to do Arch tasks from within Emacs. This tutorial will make use of it, but will also provide command line equivalents of each action.

History

There used to be a project called Xtla, which was only for use with GNU Arch and Ubuntu's Baz. It is now being generalized for use with other revision control systems like Bazaar, Monotone, and Darcs, and with that generalization the developers decided to changes its name to DVC (Distributed Version Control for Emacs). It hasn't seen a release yet (its predecessor has gone through several releases, however), but its GNU Arch handling code is very stable.

You can get the latest DVC snapshot at http://download.gna.org/xtla-el/dvc-snapshot.tar.gz. For a quick install, do mkdir ++build, cd ++build, ../configure, make, and make install. Then just add the following to your .emacs, and you're ready to begin using it.

(require 'tla)
(require 'tla-browse)

What changes did I make?

If you have at least a mild case of AD(H)D like me, it's easy to forget to document a ChangeLog entry that you made. In order to see every change that you made to a source tree, navigate to a file or directory that is part of your source tree and type C-x T =. The command line equivalent of that is the following.

tla changes --diffs

Anatomy of a change log entry

Summary line

You should make a one-line description of the changes you are making and put it in the Summary field. Don't use word wrap on this line. Don't make it longer than 80 characters.

Keywords field

I usually don't add any text to this line. You can use it for whatever you want, really. If this line does not exist in your log message when you try to commit, Arch throws a tantrum, so keep it there.

Blank lines

You must have at least one blank line separating the Keywords field and the meat of the commit log. If you omit the commit log, you still need one blank line, which is inserted by default when you first make the log.

Detailed log entries

This optional part comes after the other parts. You can put anything you want in here. Preferably, the text should be wrapped at a particular column and should present an itemized list of changes.

Where do I put change log entries?

Method that requires the least amount of work

If you are not using DVC, use the tla make-log command in your top-level working directory. Edit the new file that is created as described in the Anatomy of a change log entry section.

If you are using DVC, bring up a list of changes that you made as described in the What changes did I make? section. On each hunk of the displayed differences, type C-x T a. This opens up a log file (creating one if it doesn't already exist) and begins a sort of ChangeLog entry. Complete each entry with a description of the changes you made.

Terminology note

When you are ready to finalize your changes to a project, you perform a commit. Before doing a commit, you should make a log message that describes the changes you made.

Commit your changes

There are two ways to perform the commit. One way is to type C-c C-c in the commit log buffer. Another way is to type M-x tla-commit in any buffer that corresponds to a file or directory in your source tree. The command line version follows.

tla commit

Viewing log entries

Arch has the ability to output a somewhat non-standard ChangeLog based on your commit log messages. To see it in Emacs, do C-x T l or M-x tla-changelog. Alternatively, run the following tla command. $PAGER represents your file viewer of choice.

tla changelog | $PAGER

Auto-generated ChangeLog file

Instead of maintaining a separate ChangeLog file with your project, you could opt to have Arch keep a ChangeLog file up to date automatically whenever you commit a change. This is not recommended, because it can be very inflexible to work with.

To set up the ChangeLog file, run the following commands in the top level of your source tree.

tla changelog > ChangeLog

tla add ChangeLog

Then make a commit. From this point on, Arch will automatically update your ChangeLog file for you whenever you commit changes.

[ Previous is Part 1: Getting Started With Arch ]
[ This is Part 2: Developing With Arch ]
[ Next is Part 3: Cooperation and Arch ]

Arch Tutorial

---

[ Front | Projects | Index | Source ] Last updated Aug. 10, 2006