


readme(aegis)					    readme(aegis)


NAME
	aegis -	project	change supervisor
	Copyright (C) 1990, 1991, 1992,	1993, 1994 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)


NEW IN THIS RELEASE
	A number of features have been added to	aegis with this
	release.  A few	of them	are detailed here:

	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.




								3





readme(aegis)					    readme(aegis)


	* 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.

	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
	aux/CHANGES.2.2	file included in this distribution.

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.2.tar.Z	# the complete source
	    File:   aegis.2.2.patch.Z	# patch	to take	2.1 to 2.2
	    File:   aegis.2.2.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 <pab@ftp.cse.nau.edu>



								4





readme(aegis)					    readme(aegis)


	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-
	by-email, instead.

BUILDING
	Instructions on	how to build and test the aegis	program
	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



								5





readme(aegis)					    readme(aegis)


	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.

AUTHOR
	Peter Miller   UUCP	  uunet!munnari!bmr.gov.au!pmiller
	/\/\*	       Internet	  pmiller@bmr.gov.au





								6


