.\" .\" aegis - project change supervisor .\" Copyright (C) 1991-1993, 1998, 2001 Peter Miller; .\" All rights reserved. .\" .\" 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 2 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, write to the Free Software .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. .\" .\" MANIFEST: User Guide, How Aegis Works, The Model .\" .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. Unfortunately, this environment was the largest experienced by the author to date, and consisted of only about forty software engineers working on a single project.\** .FS "Unfortunately," because many real-world projects are far larger, but the author has yet to experience, and understand, the issues and procedures required. (Think of problems, yes; think of real-world solutions, no.) .FE .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, with some minor exceptions. The Aegis program attempts to make as few arbitrary rules as possible. There is one mandatory file in the baseline, and one mandatory directory. The file is called .I config , and contains the per-project configuration information; the directory is called .I test , and contains all of the tests. The contents and structure of the .I test directory are also dictated by 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 to B2.n move to B1.s move right down B4: box "development" "directory" arrow from 1/3 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 "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 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 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 then left 0.75 then up 2/3 "new" "change" "undo" T1: spline -> from 1/2 then left 0.75 then up 11/12 \ then to 1/3 " 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 " develop" ljust " end" ljust " undo" ljust at T2.c - (0.5,0) T3: spline -> from 1/3 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 " integrate" ljust " begin" ljust " undo" ljust at T4.c - (0.75,0) T5: spline -> from 1/3 then right 0.5 then up 1 then to 1/3 "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 "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 "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 file 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 if it has no source files and has no tests. This is usually desired if a developer selected the wrong change by mistake. .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 ``test''. 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 ``baseline test''. 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 ``regression tests''. 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 must 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 hard 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, with out 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.