.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1993, 1998, 2001, 2002, 2004-2008 Peter Miller
.\"
.\"	This 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 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This 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, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.nh 2 "The Model"
.LP
The model of the software development process
used by Aegis
evolved and grew with time in a commercial software development environment,
and it has continued to be used and developed.
.LP
The model described here is generic, and can be adapted in a variety of
ways.  These will be described at the relevant points in the text.
.nh 3 "The Baseline"
.LP
Most CASE systems revolve around a repository:
a place where
.I stuff
is kept.
This
.I stuff
is the raw material that is processed in some way to produce the final
product,
whatever that may be.
This
.I stuff
is the preferred form for
editing or composing or whatever.
.LP
In the Aegis program,
the repository is known as the
.I baseline
and the units of
.I stuff
are
.UX
files.
The Aegis program makes no distinction between
text and binary files,
so both are supported.
.LP
The history mechanism which must be included in any repository function is not
provided by the Aegis program.
It is instead provided by some other
per-project configurable software,
such as RCS.
This means that the
user may select the history tool most suited to any given project.
It also means that Aegis is that much smaller to test and maintain.
.LP
The structure of the baseline is dictated by the nature of each project.
The Aegis program attempts to make as few arbitrary rules as possible.
There is one mandatory file in the your project baseline.  The mandatory
file is called \fIaegis.conf\fP by default, and contains the per-project
configuration information.  The name of this file may be changed if
you want to call it something different.  It ios also common (though
not mandatory, and the name may be changed) to have a directory called
\fItest\fP which contains all of the test scripts.  The contents and
structure of the \fItest\fP directory (or whatever you call it) are
controlled by a test filename pattern you supply to Aegis.  Tests are
treated just like any other source file, and are subject to the same
process.
.LP
The baseline in Aegis has one particular attribute:
it always works.
It is
always there to show off to visiting big-wigs,
it is always there to
grab a copy of and ship a "pre-release snapshot" to some overly anxious
customer,
it is always there to let upper management "touch and feel"
the progress being made towards the next release.
.LP
You may claim that "works" is comfortably fuzzy,
but it is not.
The baseline contains not only the source of a project,
but also the tests for a project.
Tests are treated just like any other source file,
and are subject to the same process.
A baseline is defined to "work" if and only if it passes all
of its own tests.
The Aegis program has mandatory testing,
to ensure
that all changes to the baseline are accompanied by tests,
and that
those tests have been run and are known to pass.
This means that no
change to the baseline may result in the baseline ceasing to work\**.
.FS
Well,
mostly.
It is possible for this restriction to be relaxed if you feel
there are special circumstances for a particular change.
The danger is that a change
will be integrated with the baseline when that change
is not actually of acceptable quality.
.FE
.LP
The model may be summarized briefly:
it consists of a
.I baseline
(master source),
updated through the agency of an
.I integrator ,
who is in turn fed
.I changes
by a team of
.I developers .
These terms will be explained in the following sections.
See figure 1 for a picture of how files flow around the system.
.KF
.PS
down
B1: box "baseline"
move left down
B2: box "development" "directory"
move right down
E1: ellipse "integrator"
arrow "integrate " rjust "begin " rjust
B3: box "integration" "directory"
S1: spline -> from B3.s then down then right 1.25 then up \
	then to B1.n right 1.25 then to B1.n up right 1.25 \
	then to B1.n up then to B1.n
"integrate " rjust "pass " rjust at S1.c+(1.25,-0.75)
arrow from B2.s to E1.nw
arrow from 1/3<B1.sw,B1.se> to B2.n

move to B1.s
move right down
B4: box "development" "directory"
arrow from 1/3<B1.se,B1.sw> to B4.n
arrow from B4.s to E1.ne
.PE
.ce 1
\fBFigure 1:\fP Flow of Files through the Model
.sp
\|
.KE
.LP
The baseline is a set of files
including the source files for a projects,
and also all derived files (such as generated code,
binary files from the compiler,
etc),
and all of the tests.
Tests are treated just like any other source file,
and are subject to the same process.
All files in the baseline are consistent with each other.
.LP
Thus the baseline may be considered to be the
.I closure
of the source files,
in mathematical terms.
That is,
it is the source files
and all implications flowing from those source files,
such as object files and executables.
All files in the baseline are consistent with each other;
this means that development builds can take
object files from the baseline rather than rebuild them
within the development directory.
.LP
The baseline is readable by all staff,
and usually writable by no-one.
When it is necessary to write to the baseline,
this is done by Aegis,
as will be shown below.
.LP
In many ways,
the baseline may be thought of as a database,
and all derived files are projections (views) of the source files.
Passing its own tests may be thought of as input validation of fields.
This is a powerful concept,
and indeed the implementation of the Aegis program performs many
of the locking and synchronization tasks demanded of a database
engine.
.LP
All of the files forming this database are text files.
This means that they may be repaired with an ordinary text editor,
should remedial action be necessary.
The format is documented in section 5 of the reference manual.
Should you wish to perform some query not yet available in Aegis,
the files are readily accessible to members of the appropriate
.UX
group.
.LP
Tests are treated just like any other source file,
and are subject to the same process.
.nh 3 "The Change Mechanism"
.LP
Any changes to the baseline are made by atomic increments,
known (unoriginally)
as "changes".
A change is a collection of files to be added to,
modified in,
or deleted from,
the baseline.
These files must all be so altered
simultaneously for the baseline to continue to "work".\**
.FS
Whether to allow several logically independent changes to be included in the
one change is a policy decision for individual projects to make,
and is not dictated by the Aegis program.
It is a responsibility of reviewers
to ensure that all new and changed functionality is tested and
documented.
.FE
.LP
For example,
if the calling interface to a function were changed in one file,
all calls to that function in any other file must also change for the
baseline to continue to work.
All of the files must be changed simultaneously,
and thus must all be included in the one change.
Other
files which would logically be included in such an change include the
reference manual entry for the function,
the design document relating
to that area of functionality,
the relevant user documentation,
tests
would have to be included for the functionality,
and existing tests may
need to be revised.
.LP
Changes must be accompanied by tests.
These tests will either establish that a bug has been fixed
(in the case of a bug fix)
or will establish that new functionality works
(in the case of an enhancement).
.LP
Tests are shell scripts,
and as such are capable of testing anything which has functionality
accessible from the command line.
The ability to run background processes allows even client-server
models to be tested.
Tests are thus text files, and are treated as source files;
they may be modified by the same process as any other source file.
Tests usually need to be revised as a project grows and adapts
to changing requirements,
or to be extended as functionality is extended.
Tests can even be deleted if the functionality they test has been deleted;
tests are deleted by the same process as any other source file.
.nh 3 "Change States"
.LP
As a change is developed using Aegis,
it passes through six states.
Many Aegis
commands relate to transitions between these states,
and Aegis performs
any validation at these times.
.LP
The six states of a change are described as follows,
although the various state
transitions,
and their conditions,
will be described later.
.nh 4 "Awaiting Development"
.LP
A change is in this state after it has been created,
but before it has been assigned to a developer.
This state can't be skipped:
a change can't be immediately assigned to a developer
by an administrator,
because this disempowers the staff.
.LP
The Aegis program is not a progress tracking tool,
nor is it a work scheduling tool;
plenty of both already exist.
.nh 4 "Being Developed"
.LP
A change is in this state after it has been assigned to a developer,
by the developer.
This is the coal face:
all development is carried out in this state.
Files can be edited in no other state,
this particularly means that only developers can develop,
reviewers and integrators only have the power to veto a change.
Staff roles will be described more fully in a later section.
.LP
To advance to the next state,
the change must build successfully,
it must have tests,
and it must pass those tests.\**
.FS
It is possible for these testing requirements to be waived on either a
per-project or per-change basis.
How is described in a later section.
The power to waive this requirement is not automatically granted to developers,
as experience has shown that it is usually abused.
.FE
.LP
The new tests must also
.I fail
against the baseline;
this is to establish that tests for bug-fixes actually reproduce the bug
and then demonstrate that it is gone.
New functionality added by a change
will naturally fail when tested in the old baseline,
because it is not there.
.LP
When these conditions are met,
the Aegis program marks all of the changes files as locked,
simultaneously.
If any one of them is already locked,
you can't leave the
.I "being developed"
state,
because the file is part of a change which is somewhere
between
.I "being reviewed"
and
.I "being integrated" .
.LP
If any one of them is out-of-date with respect to the baseline,
the lock is not taken,
either.
Locking the files at this state transition means that popular files may be
modified simultaneously in many changes,
but that only differences to the latest version are ever submitted for
integration.
The Aegis program provides a mechanism,
described later,
for bringing out-of-date files in changes up-to-date without losing the
edits made by the developer.
.nh 4 "Awaiting Review"
.LP
The default configuration for an Aegis project does not use this state,
because for small-ish projects it can be tedious.  For larger projects,
however, it assists in coordinating reviewers when you use email
notification that a review is required to several potential reviewers.
.LP
To enable this state, you need to change the \fIdevelop_\%end_\%action\fP
field of the project attributes.  See \fIaepa\fP(1) for more
information, or \fItkaepa\fP(1) for a GUI interface.
.LP
It is also possible, by a different setting of the same project
attribute, to skip the code review step altogether.  This can be of
benefit to one-person projects where independent code review would be
impossible.
.LP
The rest of this description will assume the \fIawaiting review\fP state
is not being used, but code reviews \fIare\fP being used, to simplify
matters.  Once you are more familiar with Aegis, enabling the use of the
\fIawaiting review\fP state will be simple and will behave intuitively.
.nh 4 "Being Reviewed"
.LP
A change is in this state after a developer has indicated that development is
complete.
The change is inspected,
usually by a second party (or parties),
to ensure that it matches the change description as to what it is
meant to be doing,
and meets other project or company standards you may have.
.LP
The style of review,
and who may review,
is not dictated by the Aegis program.
A number of alternative have been observed:
.LP
\(bu
You may have a single person who coordinates review panels of,
say,
4 peers,
with this coordinator the only person allowed to sign-off review passes or
fails.
.LP
\(bu
You may allow any of the developers to review any other developer's changes.
.LP
\(bu
You may require that only senior staff,
familiar with large portions of the code,
be allowed to review.
.LP
The Aegis program enforces that a developer may not review their own code.
This ensures that at least one person other than the developer
has scrutinized the code,
and eliminates a rather obvious conflict of interest.
It is possible to turn this requirement off on a per-project basis,
but this is only desirable for projects with a one person team (or maybe two).
The Aegis program has no way of knowing that the user
passing a review has actually looked at,
and understood,
the code.
.LP
The reviewer knows certain things about a change for it to reach this state:
it has passed all of the conditions required to reach this state.
The change compiles,
it has tests and it passes those tests,
and the changes are to the current version of the baseline.
The reviewer may thus concentrate on issues of completeness,
implementation,
and standards - to name only a few.
.nh 5 "Customizing Code Review Policy"
.LP
It is possible to require more than one reviewer for a change.  By
setting the \fIreview_\%policy_\%command\fP of the project configuration
file, you can pass a shell script (or other command) the relevant change
details, and the exit status will be used to determine of the change
advances to the \fIawaiting integration\fP state, or requires additional
code reviewers first.
.LP
Because it is a program, it is possible to implement almost any policy
you can think of, including particular reviewers for particular areas of
code, or that there must be 3 different reviewers, \fIetc\fP.
.nh 4 "Awaiting Integration"
.LP
A change is in this state after a reviewer has indicated that a change is
acceptable to the reviewer(s).
This is essentially a queue,
as there may be many developers,
but only one integration may proceed at any one time.
.LP
The issue of one integration at a time is a philosophical one:
all of the changes in the queue are physically independent;
because of the
.I "Develop End"
locking rules they do not have
intersecting sets of files.
The problem comes when one change would break another,
in these cases the integrator needs to know which to bounce
and which to accept.
Integrating one change at a time greatly simplifies this,
and enforces the "only change one thing at a time" maxim,
occasionally at the expense of integrator throughput.
.nh 4 "Being Integrated"
.LP
A change is in this state when the integration of the change back into the
baseline is commenced.
A (logical) copy of the baseline is taken,
and the change is applied to that copy.
In this state,
the change is compiled and tested once again.
.LP
The additional compilation has two purposes:
it ensures that the successful compile performed by the developer was
not a fluke of the developer's environment,
and it also allows the baseline to be the closure of the sources files.
That is,
all of the implications flowing from the source files,
such as object files and linked programs or libraries.
It is not possible for Aegis to know which files these are
in the development directory,
because Aegis is decoupled from the build
mechanism (this will discussed later).
.LP
To advance to the next state,
the integration copy must have been compiled,
and the tests included in the change must have been run and passed.
.LP
The integrator also has the power of veto.
A change may fail an integration because it fails to build or fails tests,
and also just because the integrator says so.
This allows the
.I "being integrated"
state to be another review state,
if desired.
The
.I "being integrated"
state is also the place to monitor the quality
of reviews and reviewers.
.LP
Should a faulty change manage to reach this point,
it is to be hoped that the integration process,
and the integrator's sharp eyes,
will detect it.
.LP
While most of this task is automated,
this step is necessary to ensure that some strange
quirk of the developer's environment was not
responsible for the change reaching this stage.
The change is built once more,
and tested once more.
If a change fails to build or test,
it is returned to the developer for further work;
the integrator may also choose to fail it for other reasons.
If the integrator passes that change,
the integrated version becomes the new baseline.
.nh 4 "Completed"
.LP
A change reaches this state when integration is complete.
The (logical) copy of the baseline used during integration has replaced the
previous copy of the baseline,
and the file histories have been updated.
Once in this state,
a change may never leave it,
unlike all other states.
.LP
If you wish to remove a change
which is in this state
from the baseline,
you will have to submit another change.
.nh 3 "The Software Engineers"
.LP
The model of software development used by Aegis has four different roles
for software engineers to fill.
These four roles may be overlapping sets of people,
or be distinct,
as appropriate for your project.
.nh 4 "Developer"
.LP
This is the coal-face.
This role is where almost everything is done.
This is
the only role allowed to edit a source file of a project.
.LP
Most staff will be developers.
There is nothing stopping a developer from also
being an administrator,
except for the possible conflict of interests
with respect to testing exemptions.
.LP
A developer may edit many of the attributes of a change while it is being
developed.
This is mostly useful to update the description of the
change to say why it was done and what was actually done.
A developer
may not grant testing exemptions (but they may be relinquished).
.nh 4 "Reviewer"
.LP
The role of the reviewer is to check a developer's work.
This review may
consist of a peer examining the code,
or it may be handled by a single
member of staff setting up and scheduling multi-person review panels.
The Aegis program does not mandate what style of review,
it only
requires that a reviewer pass or fail each change.
If it passes,
an
integrator will handle it next,
otherwise it is returned to the
developer for further work.
.LP
In a large team,
the reviewers are usually selected from the more senior
members of the team,
because of their depth of experience at spotting
problems,
but also because this is an opportunity for more senior
members of staff to coach juniors on the finer points of the art.
.LP
The Aegis programs makes some of the reviewer's task easier,
because the
reviewer knows several specific things about a change before it comes
up for review:
it builds,
it has tests,
and they have run successfully.
There is also optional (per project) additional conditions imposed at
the end of development,
such as line length limits,
or anything else
which is automatically testable.
The Aegis program also provides a
difference listing to the reviewer,
so that each and every edit,
to each and every file,
can be pointed out to the reviewer.
.LP
There is nothing stopping a reviewer from being either an administrator or a
developer.
The Aegis program specifically prevents a developer from
reviewing his own work,
to avoid conflicts of interest.
(It is possible for this
restriction to be waived,
but that only makes sense for one person
projects.)
.LP
It will occasionally be necessary to arbitrate between a developer and a
reviewer.
The appropriate person to do this would have line
responsibility above both staff involved.
Thus it is desirable that
supervisors/managers not be reviewers,
except in very small teams.
.nh 4 "Integrator"
.LP
The role of the integrator is to take a change which has already been reviewed
and integrate it with the baseline,
to form a new baseline.
The
integrator is thus the last line of defense for the baseline.
.LP
There is nothing preventing an integrator from being an administrator,
a
developer or a reviewer.
The Aegis program specifically prevents a
developer or reviewer from integrating his own work,
eliminating any conflict of interests.
(It is possible for this restriction to be waived,
but that
only makes sense for one and two person projects.)
.LP
It will occasionally be necessary to arbitrate between an integrator and a
reviewer and/or a developer.
The appropriate person to do this would
have line responsibility above all of the staff involved.
Thus it is
desirable that supervisors/mangers not be integrators,
except in very
small teams.
.LP
The baseline is readable by all developers,
but not writable.
All updates of the baseline to reflect changes produced by developers
are performed through the agency of the integrator.
.nh 4 "Administrator"
.LP
The project administrator has the following duties:
.LP
\(bu Create new changes.
These may be the result of some customer bug
reporting mechanism,
it may be the result of new functionality being
requested.
.LP
\(bu Grant testing exemptions.
By default,
Aegis insists that all changes be
accompanied by tests.
The project administrator may grant case-by-case
exemptions,
or a project-wide exemption.
.LP
\(bu Add or remove staff.
The four roles described in this section may be
assigned to,
or removed from,
specific
.UX
logins by the project
administrator.
.LP
\(bu Edit project attributes.
There are many attributes attached to a project,
only a project administrator may alter them.
.LP
\(bu Edit change attributes.
There are many attributes attached to a change,
only a project administrator may alter all of them.
.LP
A project usually has only one or two administrators at any one time.
.nh 3 "The Change Process"
.LP
This section will examine the progression of a change through the six change
states.
Most of the attention will be given to the conditions which
must be met in order to progress from one state to the next,
as this is
where the software development model employed by Aegis is most often
expressed.
.LP
See figure 2 for a picture of how all of the states and
transitions fit together.
.KF
.PS
boxwid = 1
down
S0: arrow " new" ljust " change" ljust
S1: box "awaiting" "development"
arrow " develop" ljust " begin" ljust
S2: box ht 1 "being" "developed"
arrow " develop" ljust " end" ljust
S3: box "being" "reviewed"
arrow " review" ljust " pass" ljust
S4: box "awaiting" "integration"
arrow " integrate" ljust " begin" ljust
S5: box "being" "integrated"
arrow " integrate" ljust " pass" ljust
S6: box "completed"
spline -> from 1/3<S1.nw,S1.sw> then left 0.75 then up 2/3 "new" "change" "undo"
T1: spline -> from 1/2<S2.nw,S2.w> then left 0.75 then up 11/12 \
	then to 1/3<S1.sw,S1.nw>
" develop" ljust " begin" ljust " undo" ljust at T1.c - (0.75,0)
T2: spline -> from S3.w then left 0.5 then up 1 \
	then to 1/2<S2.sw,S2.w>
" develop" ljust " end" ljust " undo" ljust at T2.c - (0.5,0)
T3: spline -> from 1/3<S4.nw,S4.sw> then left 1 then up 2.25-1/12 \
	then to S2.w
"" "" " develop" ljust " end" ljust " undo" ljust at T3.c - (1,0)
T4: spline -> from S5.w then left 0.75 then up 11/12 then to 1/3<S4.sw,S4.nw>
" integrate" ljust " begin" ljust " undo" ljust at T4.c - (0.75,0)
T5: spline -> from 1/3<S3.ne,S3.se> then right 0.5 then up 1 \
	then to 1/3<S2.se,S2.ne>
"review " rjust "fail " rjust at T5.c + (0.5,0)
T6: spline -> from S4.e then right 0.5 then up 11/12 then to 1/3<S3.se,S3.ne>
"review " rjust "pass " rjust "undo " rjust at T6.c + (0.5,0)
T7: spline -> from S5.e then right 1 then up 3.5-1/12 then to 1/3<S2.ne,S2.se>
"integrate " rjust "fail " rjust "" "" at T7.c + (1,0)
.PE
.ce 1
\fBFigure 2:\fP Change States and Transitions
.sp 2
.KE
.nh 4 "New Change"
.LP
A project administrator creates a change.
This change will consist mostly of a
description at this time.
The project administrator is not able
(through Aegis) to assign it to a specific developer.
.LP
The change is awaiting development;
it is in the awaiting development state.
.nh 4 "New Change Undo"
.LP
It is possible to abandon a change if it is in the
.I "awaiting development"
state.
All record of the change,
including its description,
will be deleted.
.LP
It is called
.I "new change undo"
to emphasize the state it must be in
to delete it.
.nh 4 "Develop Begin"
.LP
A developer,
for whatever reason,
scans the list of changes awaiting
development.
Having selected a change,
the developer then assigns
that change to herself.
.LP
The change is now being developed;
it is in the being developed state.
.LP
A number of Aegis commands only work in this state,
including commands to
include files and tests in the change (be they new files to be added to
the baseline,
files in the baseline to be modified,
or files to be
deleted from the baseline),
commands to build the change,
commands to
test the change,
and commands to difference the change.
.LP
The process of taking sources files,
the preferred form for editing of a
project,
and transforming them,
through various manipulations and
translations,
into a "finished" product is known as building.
In
the
.UX
world this usually means things like compiling and linking a
program,
but as fancy graphical programs become more wide-spread,
the
source files could be the binary output from a graphical
Entity-Relationship-Diagram editor,
which would then be run through a
database schema generator.
.LP
The process of testing a change has three aspects.
The most intuitive is that
a test must be run to determine of the functionality works.
The second
requirement is that the test be run against the baseline and fail;
this
is to ensure that bugs are not just fixed,
but reproduced as well.
The
third requirement is optional:
all or some of the tests already in the
baseline may also be run.
Tests consist of
.UX
shell scripts -
anything that can be done in a shell script can be tested.
.LP
In preparation for review,
a change is differenced.
This usually consists of
automatically comparing the present contents of the baseline with what
the change proposes to do to the baseline,
on a file-by-file basis.
The
results of the difference,
such as
.UX
.I "diff -c"
output,
is kept
in a difference file,
for examination by the reviewer(s).
The benefit
of this procedure is that reviewers may examine these files to see every
change the developer made,
rather than only the obvious ones.
The
differencing commands are per-project configurable,
and other
validations,
such as line length restrictions,
may also be imposed at
this time.
.LP
To leave this state,
the change must have source files,
it must have tests,
it
must have built successfully,
it must have passed all its own tests,
and
it must have been differenced.
.nh 4 "Develop Begin Undo"
.LP
It is possible to return a change from the being developed state to the
awaiting development state.
This is usually desired if a developer selected the wrong
change by mistake.
It also provides a method to start over on a change for some other reason.
.nh 4 "Develop End"
.LP
When the conditions for the end of development
have been met (the change must have source files,
it must have tests,
it must have built successfully,
it must have passed all its own tests,
and it must have been
differenced) the developer may cause the change to leave the being
developed state and enter the being reviewed state.
The Aegis program
will check to see that all the conditions are met at this time.
There
is no history kept of unsuccessful develop end attempts.
.LP
Most of these preconditions are determined by the use of time stamps
which are recorded for various operations, in addition to file system
timestamps on the files themselves.  Logical sequencing (\fIe.g.\fP
tests being run after building after editing) is also verified.
.LP
Note that there are 3 kinds of tests
.IP 1. 2m
If a change contains a new test or a test which is being modified,
this test must pass against the code compiled and linked in the change.
This is simply referred to as a \[lq]test\[rq].
Changes may be granted an exemption from such tests.
.IP 2. 2m
If a change contains a new test and the change is a bug fix,
this test must \fIfail\fP against the old code in the baseline.
This is to confirm that the bug has been fixed.
This is referred to as a \[lq]baseline test\[rq].
Changes may be granted an exemption from such tests.
.IP 3. 2m
Tests which already exist in the baseline may be run against the code
compiled and linked in the change.  These tests must pass.  This is
to confirm that the project has not regressed, which is why these tests
are referred to as \[lq]regression tests\[rq].
Changes may be granted an exemption from such tests.
.LP
A successful develop end command results in the change advancing from
the \fIbeing developed\fP state to the \fIbeing reviewed\fP state.
(It is also possible to advance to the \fIawaiting review\fP state or the
\fIawaiting integration\fP state.  See \fIaede\fP(1) or \fIaepattr\fP(5)
for more information.)
.nh 4 "Develop End Undo"
.LP
There are many times when a developer thinks that a change is completed,
and goes hunting for a reviewer.
Half way down the hall,
she thinks of something that should have been included.
.LP
It is possible for a developer to rescind a
.I "Develop End"
to allow further work on a change.
No reason need be given.
This request may be issued to a change in either the
.I "being reviewed"
or
.I "awaiting integration"
states.
.nh 4 "Review Pass"
.LP
This event is used to notify Aegis that the change has been examined,
by a method unspecified as discussed above,
and has been found to be acceptable.
.nh 4 "Review Pass Undo"
.LP
The reviewer of a change may rescind a
.I "Review Pass"
while the change remains in the
.I "awaiting integration"
state.
No reason need be supplied.
The change will be returned to the
.I "being reviewed"
state.
.nh 4 "Review Fail"
.LP
This event is used to notify Aegis that the change has been examined,
by a method unspecified as discussed above,
and has been found to be unacceptable.
.LP
A file containing a brief summary of the problems must be given,
and will be included in the change's history.
.LP
The change will be returned to the
.I "being developed"
state for further work.
.LP
It is not the responsibility of any reviewer to fix a defective change.
.nh 4 "Integrate Begin"
.LP
This command is used to
commence integration of a change into the project baseline.
.LP
Whether a physical copy of the baseline is used,
or a logical copy using links,
is controlled by the project configuration file.
The change is then applied to this copy.
.LP
The integrator must then issue build and test commands as appropriate.
This is not automated as some integrator tasks may be required in and around
these commands.
.nh 4 "Integrate Begin Undo"
.LP
This command is used to
return a change to the integration queue,
without prejudice.
No reason need be given.
.LP
This is usually done when a particularly important change is in the queue,
and the current integration is expected to take a long time.
.nh 4 "Integrate Pass"
.LP
This command is used to
notify Aegis that the change being integrated is acceptable.
.LP
The current baseline is replaced with the integration copy,
and the history is updated.
.nh 4 "Integrate Fail"
.LP
This command is used to
notify Aegis that an integration is unacceptable,
usually because it failed to build or test in some way,
or sometimes because the integrator found a deficiency.
.LP
A file containing a
.I brief
summary of the problems must be given,
and the summary will be included in the change's history.
.LP
The change will be returned to the
.I "being developed"
state for further work.
The integration copy of the baseline is deleted,
leaving the original baseline unchanged.
.LP
It is not the responsibility of any integrator to fix a defective change,
or even diagnose what the defect may be.