.\" .\" aegis - project change supervisor .\" Copyright (C) 1991-1999, 2002, 2003, 2005-2008, 2010, 2012 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 . .\" .bp .nh 2 "The Integrator" .LP This section shows what the integrator must do for each of the changes shown to date. The integrator does not have the ability to alter anything in the change; if a change being integrated is defective, it is simply failed back to the developer. This documented example has no such failures, in order to keep it manageably small. .nh 3 "Before You Start" .LP Have you configured your account to use Aegis? See the \fIUser Setup\fP section of the \fITips and Traps\fP chapter for how to do this. .nh 3 "The First Change" .LP The first change of a project is often the trickiest, and the integrator is the last to know. This example goes smoothly, and you may want to consider using the example project as a template. .LP The integrator for this example project is Isa. Isa knows there is a change ready for integration from the notification which arrived by email. .E( isa% \f(CBaeib \-l \-p example.1.0\fP Project "example.1.0" List of Changes Change State Description \-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\- 10 awaiting_ Place under Aegis integration isa% \f(CBaeib example.1.0 10\fP aegis: project "example.1.0": change 10: link baseline to integration directory aegis: project "example.1.0": change 10: apply change to integration directory aegis: project "example.1.0": change 10: integration has begun isa% .E) .LP The integrator must rebuild and retest each change. This ensures that it was no quirk of the developer's environment which resulted in the success at the development stage. .E( isa% \f(CBaeb\fP aegis: logging to "/projects/example/delta.001/aegis.log" aegis: project "example.1.0": change 10: integration build started aegis: cook \-b Howto.cook project=example.1.0 change=10 version=1.0.D001 \-nl cook: yacc \-d gram.y cook: mv y.tab.c gram.c cook: mv y.tab.h gram.h cook: cc \-I. \-O \-c gram.c cook: lex lex.l cook: mv lex.yy.c lex.c cook: cc \-I. \-O \-c lex.c cook: cc \-I. \-O \-c main.c cook: cc \-o example gram.o lex.o main.o \-ll \-ly aegis: project "example.1.0": change 10: integration build complete isa% .E) .LP Notice how the above build differed from the builds that were done while in the .I "being developed" state; the extra baseline include is gone. This is because the integration directory will shortly be the new baseline, and must be entirely internally consistent and self\[hy]sufficient. .LP You are probably wondering why this isn't all rolled into the one Aegis command. It is not because there may be some manual process to be performed after the build and before the test. This may be making a command set\[hy]uid\[hy]root (as in the case of Aegis itself) or it may require some tinkering with the local oracle or ingress database. Instructions for the integrator may be placed in the description field of the change attributes. .LP The change is now re\[hy]tested: .E( isa% \f(CBaet\fP aegis: logging to "/projects/example/delta.001/aegis.log" aegis: sh /project/example/delta.001/test/00/t0001a.sh aegis: project "example": change 1: test "test/00/t0001a.sh" passed aegis: project "example": change 1: passed 1 test isa% .E) The change builds and tests. Once Isa is happy with the change, perhaps after browsing the files, Isa then passes the integration, causing the history files to be updated and the integration directory becomes the baseline. .E( isa% \f(CBaeipass\fP aegis: logging to "/projects/example/delta.001/aegis.log" aegis: ci \-u \-m/dev/null \-t/dev/null /projects/example/delta.001/ Howto.cook /projects/example/history/Howto.cook,v; rcs \-U /projects/example/history/Howto.cook,v /projects/example/history/Howto.cook,v <\-\- /projects/example/delta.001/Howto.cook initial revision: 1.1 done RCS file: /projects/example/history/Howto.cook,v done aegis: rlog \-r /projects/example/history/Howto.cook,v | awk '/^revision/ {print $2}' > /tmp/aegis.15309 \fI\&...lots of similar RCS output...\fP aegis: project "example.1.0": change 10: remove development directory aegis: sh \*(L)/ip.sh example.1.0 10 pat robyn isa aegis: project "example.1.0": change 10: integrate pass isa% .E) .LP All of the staff involved, will receive email to say that the change has been integrated. This notification is a shell script, so USENET could be usefully used instead. .PP You should note that the development directory has been deleted. It is expected that each development directory will only contain files necessary to develop the change. You should keep "precious" files somewhere else. .nh 3 "The Other Changes" .LP There is no difference to integrating any of the later changes. The integration process is very simple, as it is a cut\[hy]down version of what the developer does, without all the complexity. .LP Your project may elect to have the integrator also monitor the quality of the reviews. An answer to "who will watch the watchers" if you like. .LP It is also a good idea to rotate people out of the integrator position after a few weeks in a busy project, this is a very stressful position. The position of integrator gives a unique perspective to software quality, but the person also needs to be able to say "NO!" when a cruddy change comes along. .bp .nh 3 "Integrator Command Summary" .LP Only a few of the Aegis commands available to integrators have been used in this example. The following table (very tersely) describes the Aegis commands most useful to integrators. .sp .TS center,tab(;); l l. Command;Description _ aeb;Build aecd;Change Directory aed;Difference aeib;Integrate Begin aeibu;Integrate Begin Undo aeifail;Integrate Fail ael;List Stuff aet;Test aeipass;Integrate Pass .TE .LP You will want to read the manual entries for all of these commands. Note that all Aegis commands have a .I \-Help option, which will give a result very similar to the corresponding .I man (1) output. Most Aegis commands also have a .I \-List option, which usually lists interesting context sensitive information. .nh 3 "Minimum Integrations" .\" My thanks to Jerry Pendergraft for this section. .LP The \fBaegis \-integrate\[hy]begin\fP command provides a \fB\-minimum\fP option which may be used for various reasons. The term \fBminimum\fP may be a bit counter intuitive. One might think it means to the \fBminimum\fP amount of work, however it actually means use a \fBminimum\fP of files from the baseline in populating the \fIdelta\fP directory. This normally leads to actually building everything in the project from sources and, as such, might be considered the most robust of builds. .LP Note that any change which removes a file, whether by \fIaerm\fP or \fIaemv\fP, results in an implicit \fBminimum\fP integration. This is intended to ensure nothing in the project references the removed file. .LP A project may adopt a policy that a product release should be based on a minimum integration. Such a policy may be a reflection of local confidence, or lack therof, in the projects DMT (Dependency Maintenance Tool) or build system. Or it may be based on a validation process wishing to make a simple statement on how the released package was produced. .LP Another, more transient, reason a to require a minimum integration might be when upgrading a third party library, compiler or maybe even OS level. Any of these events would signal the need for a minimum integration to ensure everything is rebuilt using the new resources. .LP The cost of a \fBminimum\fP integration varies according to type and size of the project. For very large projects, especially those building large numbers of binaries, the cost can be large. However large projects also require significant time to fully populate the delta directory. A minimum integration only copies those files under aegis control, skipping all \[lq]produced\[rq] files. In the case where a file upon which everything depends is changed, everything will be built anyway so the copy of the already built files is a waste of time. This means that sometimes a minimum can be as cheap as a normal integration. .\" vim: set ts=8 sw=4 et :