Read Me(Aegis) Read Me(Aegis) NAME aegis - project change supervisor Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Peter Miller; All rights reserved. Aegis 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 defense. DESCRIPTION Aegis is a CASE tool with a difference. In the spirit of the UNIX Operating System, Aegis 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. Aegis adds to this list with software configuration management, and true to UNIX philosophy, Aegis 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 Aegis does? Just what is software configuration management? This question is sufficiently broad as to require a book in answer. In essence, Aegis 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 Aegis 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 Aegis's major functions. It should be noted that Aegis 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. BENEFITS So why should you use Aegis? Aegis 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. Aegis 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 Aegis 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 Aegis? Recall that RCS provides file locking, but only for one file at a time. Aegis 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. Aegis allows concurrent editing, and a resolution mechanism just before the change must be integrated, meaning fewer delays for J.A.Programmer. Aegis also has strong support for geographically distributed development. It supports both push and pull models, and many distribution topologies. Aegis' normal development process is used to validate received change sets before committing them. ARCHIVE SITE The latest version of Aegis is available by HTTP from: URL: http://www.canb.auug.org.au/~millerp/ File: aegis.html # the Aegis page File: aegis..C001.README # Description, from tar file File: aegis..C001.lsm # Description, in LSM format File: aegis..C001.ae # the complete source, aedist format File: aegis..C001.spec # RedHat package specification File: aegis..C001.tar.gz # the complete source 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. Mirrors See http://www.canb.auug.org.au/~millerp/ for a list of mirror sites. Aegis is also carried by metalab.unc.edu in its Linux archives. You will be able to find Aegis on any of its mirrors. URL: ftp://metalab.unc.edu/pub/Linux/devel/vc/ File: aegis..C001.README # Description, from tar file File: aegis..C001.lsm # Description, in LSM format File: aegis..C001.spec # RedHat package specification File: aegis..C001.ae # the complete source, aedist format File: aegis..C001.tar.gz # the complete source This site is extensively mirrored around the world, so look for a copy near you (you will get much better response). MAILING LIST A mailing list has been created so that users of Aegis may exchange ideas about how to use Aegis. 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@canb.auug.org.au Please DO NOT attempt to subscribe by sending email to this address. It is for content only. How To Subscribe To subscribe to this mailing list, send an email message to majordomo@canb.auug.org.au with a message body containing the single line subscribe aegis-users 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 to which you want messages sent. Archive The mailing list is archived at eGroups. The URL is http://www.egroups.com/list/aegis-users/info.html No Files By EMail The software which handles this mailing list CANNOT send you a copy of Aegis. Please use FTP or ftp-by-email, instead. BUILDING Instructions on how to build and test Aegis are to be found in the BUILDING file included in this distribution. 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). Aegis is nothing like it, owes none of its code to that system, and is far more versatile. It turns out that the system used is nothing new, and is described in many SCM textbooks; it is the result of systematically resolving development issues for large-ish teams. Since that company decided to close down our section (the company was under attack by a hostile takeover bid) 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. Branching In 1997 the full branching support was released (it took nearly 18 months to retro-fit. The underlying data structures for projects and change sets need to be merged. While I noticed back in 1990 that they were very similar, it wasn't until branch support design was well underways that they should have been the same data structure from the beginning. Geographically Distributed Development In 1999 a conversation on the aegis-users mailing list resulted in the creation of aedist, a program which packages and unpackages Aegis changes so they can be sent by e-mail, or WWW or whatever. With 20:20 hindsight, this could have been done way back in 1991, because the basic idea builds on Aegis change process model. Windows NT Aegis depends on the underlying security provided by the operating system (rather than re-invent yet another security mechanism). However, in order to do this, Aegis uses the POSIX seteuid system call, which has no direct equivalent on Windows NT. This makes porting difficult. Single-user ports are possible (e.g. using Cygwin), but are not usually what folks want. Compounding this is the fact that many sites want to develop their software for both Unix and Windows NT simultaneously. This means that the security of the repository needs to be guaranteed to be handled in the same way by both operating systems, otherwise one can act as a ``back door'' into the repository. Many sites do not have the same users and permissions (sourced from the same network register of users) on both Unix and Windows NT, making the mapping almost impossible even if the security models did actually correspond. Most sites using Aegis and Windows NT together do so by running Aegis on the Unix systems, but building and testing on the NT systems. The work areas and repository are accessed via Samba or NFS. LICENSE Aegis 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. Aegis 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., 59 Temple Place, Suite 330, Boston, MA 02111, USA. It should be in the LICENSE file included in this distribution. AUTHOR Peter Miller E-Mail: millerp@canb.auug.org.au /\/\* WWW: http://www.canb.auug.org.au/~millerp/ RELEASE NOTES For excruciating detail, and also acknowledgments of those who generously sent me feedback, please see the etc/CHANGES.* files included in this distribution. In general, all the machines on your network need to be running the same release of Aegis. While the database format is backwards compatible, it is rarely forwards compatible in the face of new capabilities. A number of features have been added to Aegis with this release. A few of them are detailed here: Note: You will need to upgrade all of your Aegis machines simultaneously for this release. It introduces database changes which older Aegis release will not be able to cope with. * There is a new tkaepa(1) command, giving GUI access to the aepa(1) command. * The seclone(1) command now runs the change_file_command and project_file_command from the project config file. This is in order to be more consistent withthe aecp(1) command. * The "time safe" property described by Damon Poole mostly applies to Aegis' operation. One last area related to future times and the --delta options. There is now a warning in the instance where non-time-safe behavior may occur. * The history_put_command and history_create_command field of the project config file are strongly recommended to be identical. It is now possible to only specify the first one, and the second will default to it. * A bug has been fixed in the aeib(1) command, when the link_integration_directory field in the project config file is false. * There is a new awaiting review state, and new aerb(1) and aerbu(1) commands to go with it. It is now possible to configure your project to have changes enter the awaiting review state after aede(1), rather than the being reviewed state. It is also possible to skip the review states altogether and immediatelt enter the awaiting integration state. * There is a new modeP field for the specification of architectures in the project config file. The means that you can designate some architectures as mandatory and some as optional. See aepconf(5) for more information. * The aenbr(1) command now populates the new branch's baseline with symlinks if the project config file is set so that they would remain after an integration build. This is more consistent with the aedb(1) behaviour in the same situation. * There have been a number of changes to the web pages, accompanying the move to SourceForge, along with some corrections. * There is a new aels(1) command, which may be used to list directories, annotated with Aegis' file attribute information. * The aeclean(1) command now accepts the -Keep option, so that it reports what it would do, rather than actually do anything. * A problem with the CGI interface, which reported a bug to the user, has been fixed. Version 3.29 * The aeimport(1) command can now import CVS repositories which contain binary files. * There is a new ${Read_File_Simple} substritution. It is like ${Read_File}, but is does not substitute into the file contents. * The aecp -independent command now accepts a -output option. * There is a new ${environment} substitution, allowing you to access environment variables within substitutions. See aesub(5) for more information. * There is a new ${project-specific} substitution, allowing you to define project specific value to be inserted into various commands. See aesub(5) and aepconf(5) for more information. * The aefind(1) command now works with completed change. It searches the baseline. * A problem with using the ${source} substitution within the integrate_pass_notify_command has been fixed. It was getting the path wrong. * The batch test command is only ever invoked of there are tests to run. (This fixes a problem where it would simethimes run with no arguments.) * The web reports now bahave themselves when the names of non-longer-here user appear. * A number of errors and typos have been fixed in the documentation. Version 3.28 * There is a new aepatch(1) program, which may be used to send an receive changes using the classic open source patch format. See aepatch(1) for more information. * The general output mechanism (for listings and reports) has been rewritten to be significantly faster. * Numerous small things have been improved in and around the * The web interface has been improved. It should result in better save file locations being suggested for .ae files. cgi vs downloads * Aegis now takes a baseline read lock during tests, so that the baseline doesn't move out from under your tests, causing mysterious failures. * A bug has been fixed in the subst function of the report generator. It was free()in a string twice. * There is a new ${developer email} substitution, for inserting users' preferred email addresses into commands. Useful for the state transition notification commands. * There is now more text in the aepconf(5) man page, explaining how each of the pattern fields are applied to file names. It is now explicit when patterns applied to whole file names, and when they only applied to path name elements. * A segfault has been fixed in the removed file whiteout code. * The aesub $source substitution now works in combination with the -BaseLine option. * The aegis.spec file now mentions the executables again. Version 3.27 * A bug has been fixed in the aesub(1) $delta substitution. It now works correctly for completed changes. * A bug has been fixed in aermu(1), when used in combination with the symlink farm. It no longer complains about "multiple user permissions set". * A serious bug has been fixed in the locking code. The bug meant that only one build per project could happen at a time. (There was never any risk of repository or Aegis database damage.) * A bug has been fixed in the aedist(1) command. It failed to correctly recognise files produced using the aedist -send -no-ascii-armour option. * The aecpu -unch command now deals more gracefully with files which have been removed from the project in the mean time. * There is a new change file history listing, similar to the file history report. It is much faster, much more informatuve, and less selective. Version 3.26 * Some optimizations have been done to the input parsing. Depending on your architecture, this will or won't be noticable. * The locking has been changed so that aeipass(1) takes precedence over new development builds, so that there is a guarantee that aeipass(1) will succeed in finite time. Current development builds will run to completion, but new development builds will block until the aeipass(1) gets the basline lock and subsequently completes. * The "file format error" bug in aedist(1) has been fixed. * There is a new project activity report, which is useful to project leaders to see what has been happing in the project, sorted by time and then by user name. * Aegis can now transparently cope with binary files, even if the history tool cannot. It does this by using a MIME encoding for binary files. (This can be configured away, if your history tool correctly handles binary files.) See aepconf(5) and the User Guide for more information. * There is a fix for the "file unrelated" error commonly seen on Solaris and BSD when combined with an automounter, in come cases. It relies on the bash(1) behaviour which sets the $PWD environment variable. (GNU libc does this internally to the getcwd(3) function, not all libcs do.) * The aer(1) report generator now has access to the project config file fields, through a new config field in the report generator's concept of the project state. * There is a new aer(1) $comdir substitution, which gives access to the shared state directory, configured at build time. * The aebuffy(1) now accepts a project name on the command line. * There is a new build_covers_all_architectures field in the project config file, so that you can tell Aegis that the build tool builds all architectures wimultaneouasly. See aepconf(5) for more information. * The tkaer(1) command now has a comment editor, so that you can edit your review fail comments from within the GUI. * A bug has been fixed which was caused aenbru(1) to delete one directory level too deep when the branch was removed. * There is a new getuid() function in the report generator. * This change fixed a bug in aede(1) where it would not allow a branch, created with aeimport(1), with new files which had subsequently been modified to end development, when those files had never existed in the baseline. * It is now possible for project administrators to nominate the developer in the tkaenc(1) dialog. You are presented with a pick list. * There is a new aesub(1) $history_directory substitution. This may be used in scripts which access the history tool's files directly. * There is a new change_file_undo_command field of the project config file. It is similar to the change_file_- command field (it defaults to it if unset), but is executed by all of the ``undo'' file commands. * The aede(1) command no longer cancels your build and test time stamps. This means that you don't need to re- build if you don't change anything, after aedeu(1) or aerfail(1). Version 3.25 * It is now possible to remove users who's accounts have been removed (the affects the aera(1), aerd(1), aeri(1) and aerrv(1) commands). * There is a new --description-only option to the aeca(1) command. This is useful for editing only the descrioption, and also for use within scripts. * The --file option has now been generalized to accept ``-'' to mean the standard input. This is useful in scripts. * There is a new aebuffy(1) command, which may be used to see what changes a user has outstanding. It needs X11 (Tk/Tcl) to work. Named after the xbuffy(1) command. * The tkaer(1) command now presents you with a ``detail'' button, so that you may see the change details when pwerforming a review. * The restriction that placed the function name at the start of the command line (e.g. the ``-cp'' of aecp) has been relaxed. This may now appear anywhere on the command line. * The Bourne / BASH shell aliases have been improved, so that they now preserve quoting of special characters and white space. This dates from the earliest days of Aegis. It's wonderful to have it fixed at last. * There is a new aemvu(1) command, which may be used to undo the effects of an aemv(1) command. This should prove less confusing than the previous method. * A big has been fixed in the aemv(1) command. It failed to accept the --base-relative option, even though it was documented to do so. * A bug has been fixed in the quote_tcl() report function. Is fixes the problem with getting the dollars sign into descriptions when using the tkaenc(1) command. * The SCCS section of the User Guide and example configurations have been updated and confirmed to work correctly, however I've only tested this with GNU CSSC. * A bug in the file name handling has been fixed. This was most obvious around the aecpu(1) command when you had create_symlinks_before_build turned on and you were using an automounter, but it occured at other times as well. * The aeimport(1) command now understands the SCCS format. If the comments in GNU CSSC are accurate, this also means you can import BitKeeper repositories, however I am unable to confirm this. Version 3.24 * There is a new aeimport(1) command, which may be used to import CVS archives into Aegis. * The cross branch merge has been improved so that it uses an earlier version number than it was using, resulting in a more sensable merge. * A bug has been fixed in the ${quote} substitution which incorrectly quoted the exclamation mark (!). Unfortunately, quoting isn't at all simple, because you can't exclusively use single quotes or double quotes or backslash. * There is now a ${change description} substitution, allowing you access to the brief description of a change in a substitution. (The suggested RCS history command have been changed to use it.) * A Dutch localization of the error messages has been contributed. * Project administrators can also use the aeibu(1) command. Handy for abandoned integrations which inconvenience everyone else. * There is a new project config file field, called build_covers_all_architectures, which allows you to tell Aegis that your build process can cover all architectures simultaneously. * The ${quote} substitution has been fixed to correctly quote more characters. It now prefers the single quote (but is is npt possible to use this exclusively). * The web site now uses PDF files for documentation, rather than gzipped PostScript. This was for lots of reasons, including the fact theat many folks couldn't work out how to print them, and also IE decompressed them ``for free'' but left the .gz suffix. * The report generator, aereport(1), can now access fields of the email address in various reports. * The ``aecp -delta'' command now adds removed files to the change as removed files instead of adding them as copied- but-empty files. This should make reproducing projects more accurate, but you need to use aermu(1) to get rid of them ,rather than aecpu(1). * The aedist program now adds a ``Content-Disposition'' header to the files it generates. This means MIME programs will unpack it into a correctly named file more often. Numerous build problems have been fixed, both for Unix and for Cygwin (Windows). There have benn some test script improvements, too. Contributions have started to roll in using the ``aedist'' format. This is very encouraging. The instructions for how to do this are contained in the ``Howto'', in the Developer section. Version 3.23 * A bug has been fixed which caused the report generator change_number function to give garbage answers for change number zero (fortunalely, not very common). * There is a new mtime function in the report generator. * There is a new aecomp utility, which may be used to compare two active changes, using tkdiff. * A bug in ``aesub ${dd}'' which reported the wrong directory when applied to branches, has been fixed. * The project config file now contains two new fields, create_symlinks_before_integration_build and remove_- symlinks_after_integration_build, which may be used to better control the behavior of the symlink farm at integration time. (Default behavior is backwards compatible.) * A new utility called tkaer has been contributed. It is for reviewing, and shows you lists of files. When you click on one, it launches tkdiff(1) to examine it. You're going to like this one, folks! * The aedist -receive command now preserves the testing exemptions, if possible. * A problem with very very large test runs and the --no- persevere option has been fixed. * The aenf(1) and aent(1) commands now accept --template and --no-template options, to control the use of new file templates. * A nasty Catch-22 in the aedist(1) command has been fixed, involving the (unnecessary) use of new file templates, when the actual template files don't yet exist in the --receive development directory. Version 3.22 * Please Note: Some code has been added to Aegis to assist in diagnosing problems when restoring projects from backups. If you see a message ``aegis: project- path: has been tampered with (fatal)'' this means there are problems with the project file ownerships. The project owner needs to be >= AEGIS_UID (defaults to 100), and the project group needs to be >= AEGIS_GID (defaults to 10). Use chown -R and/or chgrp -R to fix these problems. * The aesub(1) command now accepts the ${arch} substitution in combination with the -baseline option. * A bugs has been fixed in the aedist -receive command, when one of the files was also locked for review. * A bug in aeclone(1) has been fixed, where it dropped file move information. * The aeib(1) command now correctly validates that youare actually allowed to do this integration. This may win the prize for the oldest Aegis bug. * There is a new ${search_path_executable} substitution. See aesub(5) and aet(1) for more information. * Line wrapping in reports works properly again for lines with no white space. The previous release broke it when the wide output generalization was added. * The aet -nopersever option works again. The previous release broke it when the batch test support has implemented. * A problem with the aeb(1) command which made it difficult to use with th symbolic link farm (in some cases) has been fixed. * A new report is available from the web interface, showing a change-of-state histogram over time for all state transitions (not just the integrate pass transitions). * A problem with the aenf(1) command which made it difficult to use with th symbolic link farm (in some cases) has been fixed. * The aeipass(1) command now preserve file mod times across history updates, if the history tool gratuitously changes them. * The Solaris and IRIX build problems (wputc, et al) has been fixed. * Numerous documentation patches were received and have been applied. Version 3.21 * A couple of minor bugs have been fixed in aedist, especially the problem with sending an baseline image while a change is being reviewed. * A couple of bugs have been fixed in the tkae* commands, in partucular they no longer leave temporary files lying around. * Lots of stuff has been added to the HOWTO: a cheat sheet, how to change a project's owner, how to use distributed development, how to become a developer. * The problem which caused `aesub ${copyright_years}' to contain duplicates has been fixed. * There have been Y2K fixes: the date parsing for the -delta-date option has been fixed, and the web page data has also been fixed. * The aet(1) command can now run more than one test at once, if configured appropriately. This is of most use on systems with more than one CPU. * The -UNFormatted option no longer truncates column values. * The aesub(1) command now accepts the -baseline option, so that you can get project-specific substitution in shell scripts. * A bug has been fixed in tkaenc(1) which gave incorrect testing ssttings. It now also tracks the project testing exemptions. * A bug in aenf(1) has been fixed which allowed multiple instances of the same file to be created. * A bug has been fixed which caused `aesub ${search_path}' to fail in some cases. * A bug has been fixed in aenf(1) which allowed you to create the same file multiple times, corrupting Aegis' database and causing aede(1) to report mysterious errors. Use aenfu(1) multiple times to untangle things. * Information has been added to the section 5 manual pages, detailing how to access state information from within the report generator. This should make writing report scripts a little easier. * A bug has been fixed which caused Aegis to misbehave when launched by some versions of cron(8) or at(1). Version 3.20 * The aeib command is now more robust about ``foreign'' files in the baseline (e.g. root-owned core files). * A bug has been fixed in the ${administrator_list} substitution. * A bug has been fixed in the aedist --delta option, which caused it to dump core. * There is now a section in the History Tool chapter of the User Guide describing how to add checksums to your history files, in order to detect file corruptions. It is a general technique which applies to most history tools (including RCS). * A bug has been fixed which caused aeclone to misbehave badly when dealing with removed files. * There is now an embryonic ``How To'' document for Aegis. Please feel free to contribute subjects. * You can now say ``-BRanch -'' as a synonym for the ``-TRunk option, for those commands which accept it. * The report generator now copes with more types of empty lists. * A bug has been fixed which caused a core dump instead of a useful error message if you tried to create an alias with an illegal name. * A bug has been removed which left undeletable branch aliases if a branch was removed. * A bug has been fixed in aenbru which failed to remove the branch development directory . * The aenf(1) command now behaves better when you do horrible things like turn the files you created into directories without telling Aegis first. * A couple of small bugs have been fixed in the aenpa(1) command, both in error situations. * A bug with the -interactive option has been fixed. It will actually ask you, now. Version 3.19 * You can now run a command to generate new file templates if you want, rather than using a simple string substitution. See aenf(1), aent(1) and aepconf(5) for more information. The existing functionality is still there. * There is a new ${SUBSTitute} substitution, which provides regular expression substitutions. This is useful in new file templates. * A bug has been fixed which allowed aede of a branch when there were some kinds of outstanding changes. * The automatic change number guessing has been improved slightly, and will cope with some more variation in the development_directory_template field. * There are two new commands, aenpa(1) and aerpa(1) for creating and removing project aliases. This means that you can give project branches more meaningful names. * There is a new aesub(1) command. It substitutes its arguments and prints them, rather like the echo(1) command. This is useful when you need access to the Aegis substitutions in a script. * The command line option ``--'' is now understood. It means ``the rest of the arguments on the command line are filenames or strings''. Because this makes the options on the command line more "order sensitive" than usual, use with care. * There is a new tkaenc(1) command, allowing you to create new change via a Tcl/Tk GUI. (And a problem with TCL special characters in description text has been fixed.) * The aenf(1) command now does the right thing with directories named on the command line. In particular, you can now use ``aenf .'' to import whole directory trees. * There is a new State-File-Name list type, useful when writing cookbooks or makefiles to keep a web page in sync with a change. * There is a new ${capitalize} substitution, useful for putting in new file templates. * A bug has been fixed which caused aeclean to delete the development directory of changes with no files. Version 3.18 * A bug has been fixed which caused aecp -delta to dump core in some cases. * A bug has been fixed which caused the create-symlinks- before-build functionality to create symlinks to deleted files. * Still more typos and minor errors have been corrected in the documentation. * The aerp(1) man page has been moved to aerpass(1). Similarly for aerfail(1), aeipass(1) and aeifail(1). This should make things easier for users to find the man pages. Version 3.17 * Another aedist bug has been fixed - unfortunately it was introduced while trying to fix the last one. * A Cygwin 20.1 portability bug has been fixed. * There is a new ${dirname_relative} substitution. This is useful in new file templates, and also some configured commands. Version 3.16 * There is a new tkaeca command. It is a GUI interface to the aeca(1) command, using Tcl/Tk. * There are two new reports available: the Project- Branches and Project-Active-Branches reports may be used to query about branches within a project. * A bug has been fixed in the aedist -receive duplicate suppression code. It was complaining about user permissions. * A bug has been fixed in aeb(1), which did strange things if you tried to build an unbuildable change. * There is a new -No-WhiteOut option for the aerm(1) and aemv(1) commands, letting you suppress the ``whiteout'' files, along with some explanation in the man page about why they are there. See aerm(1) for more information. * The default value of the ``maximum_filename_length'' field of the project config file has been raised from 14 to 255. If your project depends on the old default value, you will need to set it explicitly. * The aedist -receive command now accepts a -directory option, so you can specifiy the location of the development directory. Version 3.15 * The ``aedist -receive'' command now accepts a -delta option, allowing a received change set to be applied to an historical version. * There is now some information about managing super- projects and sub-projects in the Branching chapter of the User Guide. * The aenpr(1) command now accepts a -keep option, so that you can re-attach projects moved after using the aermpr -keep command. See aenpr(1) for more information. * The aenpr(1) command now accepts -edit and -file options, allowing you to specify project attributes when creating the project. See aenpr(1) for more information. * If the project developers_may_create_changes attribute is true, the aencu(1) command now allows developers to destroy changes they created. * There is a new add_path_suffix substitution, for manipulating search paths. See aesub(5) for more information. * There are 3 new substitutions: ${bindir}, ${datadir} and ${libdir}. These are replaced by the ./configure options of the same name (or the values calculated, if none were given to ./configure). The old ${lib} substitution is deprecated in favour of the new ${datadir} substitution. See aesub(5) for more information. * Some changes have been made which increases portability, particularly the Linux libc5 vs libc6 differences. * Some changes have been made which increases portability, particularly for Windows NT. This isn't to say Aegis works under Windows NT yet, but it helps the porting efforts. Don't forget to run the mkpasswd and mkgroup utilities included in the Cygwin system. Version 3.12 * The way the Apache config files are scanned for and read has been changed, to adapt to recent Apache changes. The ./configure script will now find it more often. * The ``aedist -receive'' command has been enhanced to be more robust about change sets without headers (some browsers generously strip them all off. * A bug has been fixed in the ``aedist -receive'' command which sometimes caused decompression failures. An unfortunate interaction with the Windows NT support caused CRLF sequences in the compressed data to be mangled in some cases. * The wrong include file was being used for zlib. This has been fixed, so it should build more easily now. * The way MANPATH is handled on Linux has been improved in the chsrc and profile commands. It will not over-ride /etc/man.config now. * The aegis.cgi script has been made more robust in coping with aedist errors. * The symlink_exception field of the project config file now accepts filename patterns, not simply literal filenames. * There was a problem compiling with gcc 2.8, involving the header. This has been fixed. Version 3.11 * The aet(1) command now accepts a --force option, forcing tests to be run, even if Aegis doesn't think they need to. * The Aegis CGI interface has been enhanced so that you can download changes from the generated web pages listing the changes, using the aedist command. * The aedist --send command now accepts a --no-ascii- armor option, which leaves off the MIME base 64 encoding. Useful for binary distributions and web servers. * There is a new trojan_horse_suspect field in the project config file. This is used by aedist --receive to check for files which could be abused to carry Trojan horse attacks. * The aedist --receive command now accepts a --trojan option which treats the incoming change set as suspect, and a --no-trojan option which treats the incoming change set as benign. * The aedist --receive command now quotes filenames (if necessary) when executing commands, thus defending against filenames which contain semicolons. * The aenbru(1) command has been implemented at last. At last! You no longer need to use the aedbu work-around. * The aedbu(1) command now gives an error if you attempt to apply it to a branch. * The aermpr(1) command may now be applied to a project with active branches, and will remove the branches as well (provided there are no active changes on any of the branches). * The dos_filename_required and windows_filename_required fields of the project config file have been enhanced to reject the brain-dead Windows special filenames such as ``aux'' et al. * The ${user} and ${project} substitutions have been enhanced to provide additional information when given an additional argument. Useful for file templates. See aesub(5) for more information. * Several portability enhacements, notably the Windows filename incompatibility has been fixed, and also the Linux stdlib.h problem. Version 3.10 * As of this release you must have zlib installed before you can build Aegis. * There is a new reuse_change_numbers project attribute, letting you control whether aenc fills in holes in the change number sequence. Defaults to true if not set. See aepattr(5) for more information. * There is a new integrate_begin_exceptions field in the project config file. This permits the user to specify file to be omitted when the integration directory copy/link is performed. * The aet(1) command has been changed so that it does not exit with an error if you have a test exemption but no tests. This is no longer an error. * There is a new aedist(1) command, which may be used to send and receive Aegis change sets via e-mail and the web. * The aeclone(1), aenbr(1), aenc(1) commands now accept a -output option, a file to contain the automatically generated change number. This greatly assists in writing scripts. See the man pages for more information. * The aent(1) command now accepts a -output option, a file to contain the automatically generated file name. See the man pages for more information. * There is a new compres_database field in the project attributes, allowing the Aegis database to be stored in a compressed form (using the GNU Zip algorthm). Unless you have an exceptionally large project, coupled with fast CPUs and high network latency, there is probably very little benefit in using this feature. (The database is usually less than 5% of the size of the repository.) On slow networks, however, this can sometimes improve the preformance of file-related commands. Version 3.9 * A bug in the merge command has been fixed. It no longer deletes all of your change source files if one of the merge commands fails. * There is a new tkaegis command, using Tk/Tcl to give Aegis a GUI. Contributed by Graham Wheeler . Please report tkaegis bugs and suggestions to Graham. * The integrate pass command has been enhanced to cope with RCS and SCCS expanding keywords in source files (modifying the repository) on check-in. This can be ignored, or a warning can be issued, or it can be a fatal error (this is the default). See aeipass(1) for more information. * The worked example in the User Guide has (finally!) been updated to use the new branch numbering. Numerous spelling errors have been corrected. * The developer section of the worked example chapter now also includes discussion of some common questions raised by folks evaluating Aegis. It covers insulating development directories from the baseline, partial check- in and collaboration. * The aesub(5) man page now brings attention to the fact that the ${Copyright_Years} substitution contains spaces. You often need to quote it. * The man pages which mention filename limitations, now also note that where underlying file-system has stricter filename length limitations than the filename_maximum_- length field in the project config file, the file-system wins. Mention of this is now also present in aedb(1), etc; Linux UMSDOS is highlighted as problematic. * Aegis can now collect code metrics. See aeb(1) and aeipass(1) for more information. * There are three new report functions available: quote_url, quote_html and unquote_url. These are all for use when creating Aegis reports for the CGI interface. See aer(5) for more information. * There are several new substitutions available. These include subst, trim_extension, trim_directory, and trim_filename. See aesub(5) for more information. * The integrate_q.sh script now works correctly for branches. * Numerous configure, make and install problems have been fixed for a variety of portability targets. * The RPM spec file has been corrected to use appropriate file attributes. Version 3.8 * Some users were unable to build the previous release, due to inconsistent wide character support by the various UNIX vendors. This has now been fixed. * There are two new substitutions, trim_directory and trim_extension, which are useful for constructing file templates. These can be very useful in constructing skeletons of C++ classes. * Some changes have been made to pathname handling to better cope with automounters. See aegis(1) for more information (see discussion of the AEGIS_AUTOMOUNT_POINTS environment variable). This assumes that paths below the automounter's mount directory are echoes of paths without it (e.g. /home is the trigger, and /tmp_mnt/home is where the NFS mount is performed, with /home appearing to be a symlink). Version 3.7 * The aeifail(1) and aerfail(1) commands now have a new --reason option, to specify the failure reason on the command line, rather than in a file. * Some file operations are now faster. Mostly, this applies to operations which mention many files, and to projects with large numbers of files. Smaller projects may not notice any improvement. * There is a new --delta-date option to the aecp(1) command, allowing deltas to be extracted by date. This change also had the side-effect of making extraction by delta number more accurate on branches. * There is a new --base-relative option to most of the file manipulation commands, aecp(1), aenf(1), etc. This option may be used to specify that relative filenames are relative to the base of the source tree, rather than the current directory. There is also a related user preference, see aeuconf(5) for more information. * There is a new ``aeclean'' command. It can be used to clean your development directories of non-source files. See aeclean(1) for more information. * The aeb(1) command now passes through arguments of the form name=value, on the assumption that these are variable assignments for th ebuild tool. Previously, they were ``resolved'' as if they were file names. * A serious bug in the error and interrupt handling has been fixed. This bug would sometimes case Aegis to hang, and eventually run out of stack, when the user attempted to interrupt Aegis using ^C. Version 3.6 * The diff3_command field of the project config file has been replaced by a merge_command field. It works exactly the same way, but Aegis moves the files around first, so that the output replaces the change source file. This results in fewer ``lost'' merges. Those of you who have been hacking the diff3_command to move the files around will need to take the moves out when you rename the diff3_command field to be the new merge_command field. * The columnizing functions used by the report generator and the listings has been enhanced to understand international character sets. This allows native character sets to be used in comments and descriptions, without getting gibberish (C escapes) in the output. * There is a new shell_safe_filenames field in the project config file. This field controls whether filenames are required to be free of shell special characters. This field defaults to true if not set, so if you are using any ``interesting'' filenames, you may need to explicitly set this field to false. (You still can't use spaces or international characters in filenames.) * There is a new ${quote} substitution for insulating shell special characters in filenames in the commands in the project config file. * A number of bugs relating to environment variables have been corrected; this will make the aereport and aefind commands behave more consistently, with respect to the aegis command. * A bug has been fixed which caused the final newline of new test files to be omitted. * A bug which prevented the ``aeb -minimum'' option from working in any non-trivial case has been fixed. Version 3.5 * A bug was fixed in the lock waiting code. Aegis will now correctly wait for locks when there are several users blocking on the same lock. Version 3.4 * There is a new ``aegis -clone'' command, used to replicate changes across branches. See aeclone(1) for more information. * There is a new ``-No-Wait'' command line option, which asks for a fatal error if a lock cannot be obtained immediately; this applies to all commands which takes locks. See aeuconf(5) for more information. Version 3.3 This release is a bug fix release, and mostly install and portability bug, at that. * The problem with errno defines messing up glue.c has been fixed. * Numerous fixes to the wide character support, to cope with the vagueries of wide character support on many platforms. * The problem with the LINES and COLS environment variables messing up testing have been fixed. Some tests gave false negatives because of this. * There is a new aeb -minimum option, for use with symbolic links, only, which has a minimal set of source file links, rather than everything in the baseline. Version 3.2 * There are some additional reports available via the web interface. They are mainly to extract error causes and trends from the project history statistics. * There have been a number of minor bug fixes concerning the handling of old 2.3 projects. This should ease transition for users with existing 2.3 projects. * A bug in aecp -delta has been fixed, where Aegis was trying to find change state files one branch level too high. * There is now a re-try performed when a stale NFS file handle error is detected. This should make it easier for some sites which are heavily networked. * There have been some improvements to the way Control-C is handled. It should be more responsive when waiting for locks. * Project administrators may now end development of a branch. Since branches can endure for months or years, the orginal branch creator may have moved on. This copes with this situation. Version 3.1 Version 3.0 was not used by many sites. It was available as beta software for about a year, in numerous incarnations. Version 3.1 is the first completely stable version since adding full branching support. Version 3.0 Version 3.0 is fully backwards compatible with earlier versions, however once a project has been used under 3.0, it will not be possible to revert, e.g. to version 2.3, without restoring the project's ``info'' directory from backup. While this was generally true of previous releases, any additional state information was usually undo-able with vi(1). This time the process is much more involved because the project state files and the change state files have been combined as a necessary step in implementing branches. Version 3.0 Major New Features * Aegis now has a feature known in the literature as long transactions, also known as branches. This allows appropriately created changes to be treated as if they were projects, and thus to have changes made to them. This allows a hierachy of changes within changes, to any desired depth. See the Branching chapter of the Aegis User Guide for more information. * The project state files have been merged with the change state files. This is part of the implementation of branching. If you have written your own reports, you may need to alter them slightly. For example, in version 2.3 and earlier, reports accessed the project state file using auto p, ps; p = project[project_name()]; ps = p.state; Because the project state has been moved into a change state, the state field above now points at a change state description, and most of the old project information is contained in the branch field within it. Reports access this information as auto p, ps; p = project[project_name()]; ps = p.state.branch; Except for files, which were already present in the cstate, so access to the project file list need not change. See the new aecstate(5) for more information. * The new project command now creates branches to match the version number specified. See aenpr(1) for more information. * The error messages of Aegis have been internationalized. This affects how you build Aegis, and the environment Aegis runs in. See the BUILDING file for more information. The cshrc and profile shipped with this release set the LANG environment variable to ``en'' (for English) if you have not set it; otherwise ther error messages would be terse and uninformative. * The aet (1) command can now suggest tests to be run. This is done by correlating the source files and test files from each change. See aet(1) for more information. * There is now an aereport(1) command. The separates out the report functionality from the main body of the Aegis code, allowing the report generator to be used in places where more trust is required. * There is an intranet Web interface, which is installed automaticly when the install script discovers a web server. This interface allows browsing of much of the Aegis meta-data, of all publicly accessible projects. * There is now an aefind(1) command. This is very similar to the UNIX find(1) command, except that it finds in the unified directory stack of a change and its project. The introduction of full branch support can sometimes mean that finding a file may require looking in more than two directories; the aefind(1) command makes this simple again. Version 3.0 Minor New Features * There is now a -No_Pager option, to prevent listings and help from being redirected to a pager. There is also a user preference to more thoroughly disable paging, and a -PAGer option to override it. See aegis(1) and aeuconf(5) for more information. * There is now a -No_PErsevere option to aet(1), allowing you to request that aet(1) stop after the first test failure. There is also a user preference to set this permanently if desired, and a -PErsever option to override it. See aet(1) and aeuconf(5) for more information. * The copyright years attribute has been moved from being a project attribute to a change attribute. This is consistent with a number of other fields which have transparently moved from the project state files into the change state files, as a result of branching support. See aeca(1) and aecattr(5) for more information. * There is a new Search_Path substitution, to support builds on branches. See aesub(5) for more information. As a side effect, you can also use it in the test_command field of the project config file, and thus have a search path to look down for data files for your tests. * Test times are now remembered, so that tests are only run if they need to be. This allows you to keep working on a test, and Aegis only runs those that have not yet passed. * Aegis now uses ``fingerprints'' to tell if files have changed, rather than simply relying on file modification time stamps. While this makes Aegis more robust, there is one caveat: it is recommended that 3.0 be installed when there are no changes in the 'being reviewed' or 'awaiting integration' states, in any project. * There is now a log file prefernces control, allowing users to set their preferred logging behaviour. See aeuconf(5) for more information. * It is now possible to specify the filename for new tests on the command line. See aent(1) for more information. * It is not possible to specify a pattern for test filesnames. See aepconf(5) for more information. * There is now a -MAXimum option to the aeib command, allowing you to keep obsolete derived files at integrate begin. This can avoid long integration build times for large projects. Version 3.0 Bug Fixes * Architecture names are now checked a `develop end' time, to ensure there are no unknown variants. This fixes the mysterious ``you must build again'' problem. * The aecp(1) and aed(1) commands now take a baseline read lock, to be more symetric with the aeb(1) command which has always done so. The aeipass(1) command takes the complementary baseline write lock, ensuring the the baseline remains constant for the duration of builds, file copies, differences and merges. The manual entries for these commands have all been improved to document this behaviour. See aeb(1), aecp(1), aed(1) and aeipass(1) for more information. * There are now some reminder scripts in the library, which can be run from crontab(1). These are installed into the /remind directory. These scripts can be used to remind users of changes in various states, such as those being developed or being reviewed. * All of the commands which accept the -Edit option now also accept a -Edit_BackGround option, allowing edit commands to be piped in from the standard input. * The aecp(1) command now accepts a -INDependent option, allowing files to be copied independent of any change (similar to the -INDependent option of the command.) See aecp(1) for more information. * The aecp(1) command now accepts a -Read_Only option, allowing files to be copied into a change specifically to insulate it from baseline changes. Such files must be uncopied before development may end. See aecp(1) for more information. * The aenrls(1) command is now used only to convert pre-3.0 projects into post-3.0 projects. This is because the full branching support in 3.0 makes it more useful to create a new release of a project by ending development on the branch of the previous release and starting development of a new branch numbered for the new release. See the Branching chapter of the User Guide for more information. Version 2.3 * The merging behaviour of the aed(1) command has changed. If any files require merging, it only merges. In this way, merged files are not lost in the rest of the output. Also, there are now command line options and user preferences so that you can select to only merge or only difference. See aed(1) and aeuconf(5) for more nformation. * It is now possible to assign symbolic names to project deltas. This means that you may now recreate earlier project baselines by name. * All commands which accept a -Edit option now check for most errors before commencing the edit. This avoids wasted edits in many error cases. * Fuzzy file name matches are now used to improve the error messages from aecp, aerm, etc. * Version number separators in project names are preserved across new releases. Particularly, you can use a minus ('-') between the name and the major version number. * A new ``copyright_years'' project attribute has been added. This is a list of years maintained at integrate begin time, to automate the insertion of list of copyright years into copyright messages and documentation. There is a new ${Copyright_Years} substitution and the copyright years are also listed in the ``aegis -list version'' listing. See aesub(5) and ael(1) for more information. * It is now possible to specify patterns for acceptable and unacceptable filenames in the project config file. See aepconf(5) for more information. * Four more functions have been added to the report language: length, split, substr and wrap. See aer(5) for more information. * The tests distributed with are now more stable on very fast hosts. See the environment variables section of aeb(1) for more information. * The lib/config.example directory of the distribution now contains files with example portions of the project config file. May thanks to David R Shue for this suggestion. Changes made in the previous release included: Version 2.2 This release of Aegis provides 3 of the most commonly requested features: support for heterogeneous development, support for a greater range of DMTs, support for user-defined reports. * Aegis now supports heterogeneous development. Now you can be sure that your project not only always builds and tests sucessfully, but that it does so across a configurable set of system or hardware architectures. See the Heterogeneous Development secion of the Tips and Traps chapter of the User Guide for more information. * Aegis can now cope with a wider range of Dependency Maintenance Tools (DMTs). It now has the ability to fill development directories with symbolic links to all files in the baseline which are not present in the development directory. This allows DMTs to assume all files are present below the current directory, allowing DMTs such as cake and GNU Make to be used. See the Dependency Maintenance Tool section of the User Guide and aeb(1) for more information. * Aegis now has a report generator, so you can create your own reports. Many "canned" reports are included in this distribution; of particular interest to many will be the File_Activity report, which details currently active files. See aer(1) for more information. * Aegis is now configured using a shell script called configure, distributed with the package. This shell script is generated using GNU Autoconf. See the BUILDING file for more information. * The AEGIS environment variable has been renamed AEGIS_PATH, to bring it in line with the AEGIS_PROJECT and AEGIS_CHANGE environment variable names. The old name will keep working for some time, but aegis will warn you. * Filename lengths are now configurable. The 14 character portability limit is still the default, but a higher limit is configurable for each project, up to the filesystem filename limit. See aepconf(5) for more information. * It is now possible to specify that filenames must be within the minimum character set mandated by POSIX. The default is as before, to allow any printing character. See aepconf(5) for more information. * Limits on the length of project names have been relaxed. Project names are now only limited by the filesystem filename limit. * It is now possible to specify the command to run tests, allowing a project to use a specialized test facility, rather than be forced to use shell scripts. See aet(1) and for more information. * The commands which accept the -Edit now preserve the edited text in the event of a failure. * The commands which delete files now accept a -Interactive option, which causes them to prompt the user for confirmation of file deletion. This can be made the default by an appropriate setting of the aliases or individual users preferences files. See aenfu(1), aentu(1), aecpu(1), and aeuconf(5) for more information. * The aecp(1) command now accepts directory names, allowing whole directory trees to be copied into a change. The aecpu(1) command now has a -UNChanged option which allows the unchanged files to be uncopied. * The aeb command now accepts file names, allowing partial builds to be performed. See aeb(1) for more information. * There is a new aechown(1) command to facilitate reassigning the developer of a change which is in the being developed state. * It is now possible for project administrators to assign changes to specific developers. See aedb(1) for more information. Version 2.1 * Can now ask for history to maintained for file generated by the build. This is useful for generating patch files. Version 2.0 * A new command has been added to facilitate changing the name of a file as part of a change. See aemv(1) for more information. * It is now possible to list the locks currently held. See ael(1) for more information. * If no other defaulting mechanism is specified, aegis will now attempt to guess the project name and change number from the pathname of the current directory. This only works from within development directories. * The aenc, aeca, aerfail, aeifail and aepa commands now accept a -Edit command line argument. See the relevant manual pages for more information. * The aenpr command now understands the -MAJor and -MINOr options, allowing the initial version of a project to be something other than 1.0. * The aed command now understands the -ANticipate option. See aed(1) for more information. * It is now possible to list all the outstanding changes of a project, or of all projects. See ael(1) for more information. Version 1.4 * Support has been added for systems without the seteuid system call, or those with crippled implementations. * Most of the unimplemented command variants have been finished. These include New Change Undo, Develop Begin Undo and ReMove PRoject. Most notable of the exceptions is -ANticipate option for the -CoPy_file and -DIFFerence command. * The User Guide has been added to, making it a little more complete. It still needs more work, sigh. * The code to handle automounters has been made more robust. * The command substitutions have been vastly improved, and are now documented. Reference Manual Aegis 1