aegis-open

Getting Started With Aegis For Free Software Projects

MJ Ray

15th August 2003

This is a work in progress.

1 Aegis Revision Control
1.1 Why Revision Control?
1.2 Introducing Aegis
2 Developing an Aegis-managed Project
2.1 Not Running A Local Aegis
2.2 Running A Local Aegis
2.2.1 Concepts
2.2.2 Setting Up Aegis
2.2.3 The initial development
2.2.4 Developing a new change
2.2.5 Other useful commands
2.2.6 Dealing with failures at review stage
2.2.7 Quick reference command table
2.3 Some Common Project Management Questions
2.4 Accepting Remote Developments
2.5 Making Releases
2.5.1 Tarball
2.5.2 Patch file
2.5.3 Aegis Distribution

1 Aegis Revision Control

This section introduces the benefits of revision control in general and the particular benefits of the Aegis[1] system for distributed development teams.

1.1 Why Revision Control?

One of the major worries of distributed Free Software[2] projects is keeping control over the quality of the project's releases and merging the work of developers who may never meet. Revision control can help to ease integration and make sure that releases are of a suitably high quality. One of the main ways this is ensured is by isolating developers' work from each other until they are complete and ready to be integrated. This can be done in the small scale by not submitting the work for inclusion until it is ready, or on a larger scale by making a "branch" in the revision control system. While the work is being developed, other accepted work can be merged in by the developer, to try to avoid problems when it is submitted for release.

1.2 Introducing Aegis

Aegis[1] is a revision control system released under the GNU General Public License (GPL). The underlying aim is to try to keep a "baseline" version that always works well enough to form the basis of a release. It also addresses the concerns with CVS:

Rename support - if a filename needs to be changed, it can be renamed in the revision control system with an aegis command;
Grouping of changes - for aegis, the basic unit of development is a change to multiple files, which reflects how development normally occurs;
Distributed development - aegis comes complete with tools for communication between developers over standard connections such as web and email, which gives developers the possibility to download a change for later merging or to submit their change to an email queue for transfer in a more efficient manner.

Some of the new features available with aegis include:

Optional integration of the build system into the change development process - nothing which breaks the build is allowed into the baseline (roughly equivalent to a CVS HEAD). The work can still be shared and distributed, though, but not as part of a release.
Different build and repository formats available - an extensive project config file allows selection of the tools to be used and the development policies for the project. Automatic sending of patches is a particularly powerful feature.
Optional integration of a testing framework into the change development process - if this feature is enabled, nothing which causes unit tests and/or regression tests to fail will admitted to the baseline.

Of course, there is much more than this, including a comprehensive selection of documentation through manual pages and guides available from the developers.

2 Developing an Aegis-managed Project

For normal developers, there is little difference if the project uses aegis instead of no revision control. If you wish, you can run a local Aegis system so that you can group changes and submit them in combination as well as individually.

For the project leader, using Aegis is very simple in some ways and very different in others. At the very least, it brings you all the benefits of revision control, easy merging and makes you think a little about the quality of the code that you are adding into your releases. If you want to, it can make the use of build and testing frameworks a lot easier, too, and help you distribute patch updates to your developers as soon as they happen.

2.1 Not Running A Local Aegis

The simplest way for normal developers to work is to keep two copies of the sources that you are working on. One of these is your exact copy of the maintainer's tree and the other is the one you are working on. Once you have completed a development, you can use these two produce patches in the maintainers preferred format (usually diff -ruP original-dir changed-dir or similar).

When a new version is released by the maintainer, you can merge the released patch into your local copies of the sources (eg patch -F3 -p1 <patchfile). Occasionally conflicts may result when applying the patch to your development copy, but these are resolved in the normal way, by looking at the "rej" files to see how to add them.

2.2 Running A Local Aegis

To run a local aegis system for your changes, you need to have all the build tools that the project uses installed and correctly configured. For our projects, this is usually make, diff and fhist. You're effectively running your own copy of the aegis system used by the project leader, who does the releases.

2.2.1 Concepts

It is useful to have some concept of the model that aegis uses to represent the project. Each project may have a number of branches, representing different lines of development, eg releases. Each branch has a number of numbered changes, which are groupings of file modifications that do a particular task. Each change has a number of possible states, including "awaiting" and "under" each of "development", "review" and "integration", as well as "completed" and moves back and forth along these stages as work progresses. Once "completed", the change is part of the baseline and included in the next release.

Additionally, each project and change have attributes which define the behaviour of the project system. Setting these up correctly is vitally important. The project developer should have documented them, hopefully.

2.2.2 Setting Up Aegis

The first step is to install aegis as its own user and group (hint: groupadd aegis, useradd -m aegis) with the user you'll be working as added to the aegis group (hint: vigr). While su'd to the aegis user, create the project with aegis -npr projectname and add yourself as an administrator with aegis -na yourusername -p projectname. You can also do these steps by running the tkaegis tool.

It's a good idea to set all options you want in $HOME/.aegisrc especially emailaddress = "some@address"; and you can find a full list on the aeuconf man(1) page. Some automation may depend on correct settings.

2.2.3 The initial development

Project creator sets up their aegis, basically with:

aegis -npr -p projname.1.0.0
aegis -pa -p projname.1.0.0

and develops the initial version with:

aegis -nc -p projname.1.0.0 -c 1
aegis -db -p projname.1.0.0 -c 1 -dir /path/to/working/dir
# ... make/copy files in working dir here ...
# ... make config file out of aegis examples
# recommend: make and fhist ones
aegis -nf config # ... list of other new toplevel files/dirs ...
aegis -build
aegis -diff
aegis -test
aegis -de -p projname.1.0.0 -c 1
aegis -rb -p projname.1.0.0 -c 1
# ... review first change set here ... look for goofs ...
aegis -rpass -p projname.1.0.0 -c 1
aegis -ib -p projname.1.0.0 -c 1
aegis -build
aegis -diff
aegis -test
aegis -ipass -p projname.1.0.0 -c 1

then makes a copy of the project config file with:

aegis -pa -p projname.1.0.0 -l > projname.1.0.0.aepa

and a baseline aedist file with something like:

aedist -send -p projname.1.0.0 -bl -naa > projname.1.0.0.bl.aedist

...but that's also available from the Aegis CGI interface, if enabled.

Most of the time, you can enter your shell's equivalent of

export AEGIS_PROJECT=projname.1.0.0

if you want to save typing to avoid giving -p explicity every time.

Once the project creator has created a config file, do the following as user aegis:

aegis -npr -p projname.1.0.0 -f projname.1.0.0.aepa -dir /home/aegis/projname

Then, still as aegis, add yourself as developer, reviewer and integrator:

aegis -nd -p projname.1.0.0 username
aegis -nrv -p projname.1.0.0 username
aegis -ni -p projname.1.0.0 username

As your normal user, import the first changes file:

aedist -receive -p projname.1.0.0 -c 1 -dir /path/to/working/dir < projname
.1.0.0.bl.aedist

You will probably get a trojan warning: aedist: warning: potential trojan, review before completing development. Deal with this by building the project, creating diffs, and ending development:

aegis -build
aegis -diff
aegis -test
aegis -de

You then need to review/integrate the changes. Begin the review as follows:

aegis -rb -p projname.1.0.0 -c 1

Check in the working dir for any errors. Looking at the ,D files is a good idea. If you're happy, pass the changes:

aegis -rpass -p projname.1.0.0 -c 1

Begin integration, build, diff and pass it:

aegis -ib -p projname.1.0.0 -c 1
aegis -build
aegis -diff
cd ..
aegis -ipass -p projname.1.0.0 -c 1

2.2.4 Developing a new change

Start by making a new change with "aegis -nc":

aegis -nc -p projname.1.0.0

This takes you to an editor. Set descriptions and cause (see the docs for the full list of possibilities, including internal and external, bug, improvement and enhancement). Then start work:

aegis -db -c number -dir workingdir

eg:

aegis -db -c 10 -dir ~/aegis-luminas/projname -p projname.1.0.0

Adding files

Create files / directories as normal, then tell Aegis about them:

aegis -nf filename ...

Editing config for new files

If the new files need to be run (as part of testing or whatever) you need to edi t the configuration.

Tell aegis you want to modify it:

aegis -cp config

Then edit config. You probably want to explicitly run something, eg:

build_command =
"sh ${s application/build.sh}";

Check your changes:

aegis -build
aegis -diff
aegis -test
aegis -de

Then get them reviewed (this may be automated):

aepatch -send -c 10 -p projname.1.0.0 | \
mail -s "projname patch" email@address

or:

aedist -send -c 10 -naa -p projname.1.0.0 > projname.1.0.0.10.aedist

When the reviewer approves, pass the changes:

aegis -rpass -p projname.1.0.0 -c 10

Begin integration, build, diff and pass it:

aegis -ib -p projname.1.0.0 -c 10
aegis -build
aegis -diff
cd ..
aegis -ipass -p projname.1.0.0 -c 10

Then send out the change (this may be automated):

aepatch -send -c 10 -nco -naa -p projname.1.0.0 | \
mail -s "projname change desc" email@address

2.2.5 Other useful commands

When it goes wrong and you want to nuke the entire damn project (eek):

aegis -rmpr -p projname

2.2.6 Dealing with failures at review stage

As senior developer, do aegis -rb and aegis -rfail. Then an editor opens and you quote the salient part of failure email into it. You get dropped back to the "development" state so you can go fix the problem, and then round it goes again.

2.2.7 Quick reference command table

---|---|---
State | Action | aegis command

2.3 Some Common Project Management Questions

Do you only have one developer with access to the machine that runs the aegis which makes releases? In this case, you need to ensure that you allow the developer to review and integrate the change. As far as the local aegis system is concerned, the person who receives patches is the developer. Make sure to note in the change attributes (edit with aegis -ca) the full details of who submitted the patch, etc.

If you have multiple developers on the local system (eg a company-managed free software system), this is not such a problem, but you should probably appoint one developer responsible for sending out releases and arrange some time each week (or day) when you can ensure that both people are available to discuss anything blocking something from inclusion in a release.

Try to decide early on which of the system's facilities that you are going to use. It is quite simple to change the config later, but any remote developers running their own aegis may have to do extra work to use the new configuration (eg install new build tools).

2.4 Accepting Remote Developments

Familiarise yourself with the aepatch and aedist tools for both generating and accepting remote patches and distribution files before you need to use them. You may find it helpful to write a shell script to generate the right format files and upload them somewhere.

Decide what format you prefer submissions from remote developers to be in. Do you want them to sign their submissions with gnupg or similar? Publish this policy. Do not reject submissions that are not in the preferred format, but make it clear that ones in the correct format are likely to be integrated more quickly.

Release early, release often.

2.5 Making Releases

There are two or three stages to releasing a project from an aegis system.

2.5.1 Tarball

Everyone likes a tarball -- they mean that new developers don't have to spend years patching the last tarball up to the current cutting edge of development before they can start work. To do this, make a new directory in the form projectName-releaseNumber and run the command aegis -copy -independent -project projectName . in it (note the full stop at the end). This makes a standalone copy of the current aegis baseline, ready for make distclean or equivalent before tarring.

2.5.2 Patch file

By default, the aepatch tool produces changes in a format ready for emailing out. Although this is normally what you want, for publication on a web site, you will need to give the options aepatch -s -nco -naa and then run it through gzip -9.

2.5.3 Aegis Distribution

If you have the aegis CGI program open to the public, this is done for you.

Copyright

This work may be reproduced in any form, as long as the above copyright notice is preserved, its author is clearly attributed, all modifications are clearly marked and all recipients of a copy or derived work are granted these same rights.

References

[1] The Aegis distribution site

[2] Free Software Defintion, Free Software Foundation Europe