readme(aegis) readme(aegis) NAME aegis - project change supervisor Copyright (C) 1990, 1991, 1992, 1993 Peter Miller. All rights reserved. The aegis program is distributed under the terms of the GNU General Public License. See the LICENSE section, below, for more details. aegis (ee.j.iz) n., a protection, a defence. DESCRIPTION The aegis program is a CASE tool with a difference. In the spirit of the UNIX Operating System, the aegis program is a small component designed to work with other programs. Many CASE systems attempt to provide everything, from bubble charts to source control to compilers. Users are trapped with the components supplied by the CASE system, and if you don't like one of the components (it may be too limited, for instance), then that is just tough. In contrast, UNIX provides many components of a CASE system - compilers, editors, dependency maintenance tools (such as make), source control tools (such as RCS). You may substitute the tool of your choice if you don't like the ones supplied with the system - gcc, jove, cake, to name just a few. The aegis program adds to this list with software configuration management, and true to UNIX philosophy, the aegis program does not dictate the choice of any of the other tools (although it may stretch them to their limits). Enough hype, what is it that the aegis program does? Just what is software configuration management? This question is sufficiently broad as to require a book in answer. In essence, the aegis program is a project change supervisor. It provides a framework within which a team of developers may work on many changes to a program independently, and the aegis program coordinates integrating these changes back into the master source of the program, with as little disruption as possible. Resolution of contention for source files, a major headache for any project with more than one developer, is one of the aegis program's major functions. It should be noted that the aegis program is a developer's tool, in the same sense as make or RCS are developer's tools. It is not a manager's tool - it does not provide progress tracking or manage work allocation. 1 readme(aegis) readme(aegis) BENEFITS So why should you use the aegis program? The aegis program uses a particular model of the development of software projects. This model has a master source (or baseline) of a project, and a team of developers creating changes to be made to this baseline. When a change is complete, it is integrated with the baseline, to become the new baseline. Each change must be atomic and self-contained, no change is allowed to cause the baseline to cease to work. "Working" is defined as passing it's own tests. The tests are considered part of the baseline. The aegis program provides support for the developer so that an entire copy of the baseline need not be taken to change a few files, only those files which are to be changed need to be copied. In order to ensure that changes are unable to cause the baseline to cease to work, aegis mandates that changes be accompanied by at least one test, and that all such tests be known to complete successfully. These steadily accumulated tests form an ever increasing regression test suite for all later changes. There is also a mandatory review stage for each change to the baseline. While these requirements may be relaxed per-change or even per- project, doing so potentially compromises the "working" definition of the baseline. The win in using the aegis program is that there are O(n) interactions between developers and the baseline. Contrast this with a master source which is being edited directly by the developers - there are O(n!) interactions between developers - this makes adding "just one more" developer a potential disaster. Another win is that the project baseline always works. Always having a working baseline means that a version is always available for demonstrations, or those "pre- release snapshots" we are always forced to provide. The above advantages are all very well - for management types. Why should Joe Average Programmer use the aegis program? Recall that RCS provides file locking, but only for one file at a time. The aegis program provides the file locking, atomically, for the set of files in the change. Recall also that RCS locks the file the instant you start editing it. This makes popular files a project bottleneck. The aegis program allows concurrent editing, and a resolution mechanism just before the change must be integrated, meaning fewer delays for J.A.Programmer. 2 readme(aegis) readme(aegis) ARCHIVE SITE The latest version of aegis is available by anonymous FTP from: Host: ftp.cse.nau.edu (134.114.64.70) Dir: /pub/Aegis File: aegis.2.1.tar.Z # the complete source File: aegis.2.1.patch.Z # patch to take 2.0 to 2.1 File: aegis.2.1.ps.Z # PostScript of the User Guide To use anonymous FTP, give "anonymous" as the user name (omit the quotes) and your email address as the password. My grateful thanks to Paul Balyoz for his generosity in providing this archive space. This directory also contains a few other pieces of software written by me. Some are referred to in the aegis documentation. Please have a look if you are interested. For those of you without FTP, I recommend the use of an ftp-by-email server. Here is a list of a few (there are many more): ftpmail@decwrl.dec.com ftpmail@cs.uow.edu.au In general, you can get a help message about how to use each system by sending email with a subject of "help" and a message body containing just the word "help". MAILING LIST A mailing list has been created so that users of aegis may exchange ideas about how to use the aegis program. Discussion may include, but is not limited to: bugs, enhancements, and applications. The list is not moderated. The address of the mailing list is aegis-users@bmr.gov.au To subscribe to this mailing list, send an email message to majordomo@bmr.gov.au with a message body containing the single line subscribe aegis-users Please note that bmr.gov.au is an Internet site, so if you have an address which is not readily derived from your mail headers (majordomo is only a Perl program, after all) you will need to use a message of the form: subscribe aegis-users address where address is an email address which makes sense from an Internet site. The software which handles this mailing list CANNOT send you a copy of the aegis program. Please use FTP or ftp- 3 readme(aegis) readme(aegis) by-email, instead. COMPARISON WITH CVS One of the most common questions about aegis is "How does it compare with CVS?" The CVS program aims to provide a repository, RCS for sets of files. The aegis program aims to provide a baseline, a repository, consistency of the baseline, and validation of changes being made to the baseline. A simplistic way of thinking of this is "CVS is over RCS", but "aegis is over RCS and make". Actually CVS requires RCS, whereas aegis may be configured to use almost any history tool; similarly for the dependency maintenance tool, aegis may be configured to use almost any sufficiently capable tool (unfortunately traditional make isn't sufficiently capable, but the name is well known and evokes the appropriate functional image). The most significant point of departure is around the "cvs checkin" functionality. In CVS, this is unconditional; a developer can add a poorly though-out code change, or even indulge in a little vandalism, with nothing to prevent it. In contrast, the aegis program breaks this step into several pieces: the change must be be known to build, the change must have tests and those tests be known to have run and passed, the change must then be reviewed (double check), and then built and tested again (triple check). For a more detailed discussion, see appendix C of the User Guide. NEW IN THIS RELEASE A number of features have been added to aegis with this release. A few of them are detailed here: * Can now ask for history to maintained for file generated by the build. This is useful for generating patch files. Plus the usual crop of bug fixes and tinkering. For excruciating detail, and also acknowledgements of those who generously sent me feedback, please see the CHANGES file included in this distribution. BUILDING Instructions on how to build and test the aegis program are to be found in the BUILDING file included in this distribution. 4 readme(aegis) readme(aegis) SOME HISTORY The idea for aegis did not come full-blown into my head in the shower, as some of my programs do, but rather from working in a software shop which used a simplistic form of something similar. That system was held together by chewing-gum and string, it was written in a disgusting variant of Basic, and by golly the damn thing worked (mostly). The aegis program is nothing like it, owes none of its code to that system, and is far more versatile. Since that company decided to close down our section, we all moved on simultaneously (all 60 of us), sometimes working together, and sometimes not, but always keeping in touch. With suggestions and conversations with some of them early in 1990, the manual entries for aegis took shape, and formed most of the design document for aegis. Since getting the first glimmerings of a functional aegis late in 1990 it is increasingly obvious that I never want to be without it ever again. All of my sources that I modify are instantly placed under aegis, as is anything I distribute. All code I write for myself, and all new code I write for my employer, goes under aegis. Why? Because it has fewer bugs! Example: one of the sources I carry with me from job to job is "cook", my dependency maintenance tool. Cook had existed for 3 years before aegis appeared on the scene, and I used it daily. When I placed cook under aegis, I found 6 bugs! Since then I have found a few more. Not only are there now fewer bugs, but they never come back, because the regression test suite always grows. LICENSE The aegis program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The aegis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. It should be in the LICENSE file included in this distribution. 5 readme(aegis) readme(aegis) AUTHOR Peter Miller UUCP uunet!munnari!bmr.gov.au!pmiller /\/\* Internet pmiller@bmr.gov.au 6