.\"
.\"     aegis - project change supervisor
.\"     Copyright (C) 1999, 2002, 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
.\"     <http://www.gnu.org/licenses/>.
.\"
.nh 2 "Common Questions"
.LP
There are a number of questions which are frequently asked by people
evaluating Aegis.  This section attempts to address some of them.
.nh 3 "Insulation"
.LP
The repository model used by Aegis is of the \[lq]push\[rq] type \- that is,
changes to the baseline are \[lq]pushed\[rq] onto the developer as soon as
they are integrated.  Many configuration management systems have a
\[lq]pull\[rq] model, where the developer elects when to cope with changes in
the repository.
At first glance, Aegis does not appear to have a \[lq]pull\[rq] equivalent.
.LP
It is possible to insulate your change from the baseline as much or as
little as required.  The \fIaecp\fP(1) command, used to copy files into a
change, has a \f[CW]\-read\[hy]only\fP option.  The files copied in this way
are marked as insulation (\fIi.e.\fP you don't intend to change them).
If you have not un\[hy]copied them at develop end time, the \fIaede\fP(1)
command will produce a suitable error message, reminding you to un\[hy]copy
the insulation and verify that your change still builds and tests
successfully with the (probably) now\[hy]different baseline.
.nh 4 "Copy Read\[hy]Only"
.LP
It is possible to select the degree of insulation.  By using \[lq]\f[CW]aecp
\&.\fP\[rq] at the top of a development directory, the complete project
source tree will be copied, thus completely insulating you.  Mind you,
it comes at the cost of a complete build.
.LP
If you are working on a library, and only want the rest of the library to
remain fixed, simply copy the whole library (\f[CW]aecp library/fred\fP),
and allow the rest to track the baseline.  This comes at a smaller cost,
because more of the baseline's object files can be taken advantage of.
.nh 4 "Branches"
.LP
It is also possible to create a sub\[hy]branch (see the \fIBranching\fP
chapter).  This does not itself automatically insulate, however the
first change of a branch intended to insulate would copy and integrate
\fIbut not modify\fP the files to be insulated.  You need to remember
to perform a \fIcross\[hy]branch merge\fP with the parent branch before
integrating the branch back into the parent branch.
.nh 4 "Builds"
.LP
You can also insulate yourself from baseline change by being selective
about what you choose to build.  You can do this by giving specific
build targets on the \fIaeb\fP(1) command line, or you could copy the
build tool's configuration file and butcher it.  Remember to change it
back before you \fIaede\fP(1) your change!
.nh 4 "Mix\[hy]and\[hy]Match"
.LP
Some or all of the above techniques may be combined to provide an
insulation technique best suited to your project and development policy.
\fIE.g.\fP changing the build configuration file for a branch dedicated
to working on a small portion of a large project; towards the ed of
the development, change the build configuration file back and perform
integration testing.
.nh 4 "Disadvantages"
.LP
There is actually a down\[hy]side to insulating your changes from the
evolution of the baseline.  By noticing and adapting to the baseline,
you have much less merging to do at the end of your change set.  Each
integration will typically be be modest, but the cumulative effect could
be substantial, and add a huge unexpected (and un\[hy]budgeted for) time
penalty.
.LP
It also means that if there are integration problems between
your work and the changes which were integrated before yours, or if
your work shows up a bug in their work, the project find this out late, rather
than early.  The literature, based on industrial experience, indicates
that the earlier problems are found the cheaper they are to fix.
.LP
Insulated development directories also use more disk space.  While disk
space is relatively cheap these days, it can still add up to a substantial
hit for a large development team.  Un\[hy]insulated development directories
can take advantage of the pre\[hy]compiled objects and libraries in the
baseline.
.nh 3 "Partial Check\[hy]In"
.LP
In the course of developing new functionality, it is very common to come
across a pre\[hy]existing bug which the new functionality exposes.  It is
common for such bugs to be fixed by the developer in the same development
directory, in order to get the new functionality to a testable state.
.LP
There are two common courses of action at this point: simply include the
bug fix with the rest of the change, or integrate the bug fix earlier than
the rest of the change.  Combining the bug fix with the rest of the change
can have nasty effects on statistics: it can hide the true bug level
from your metrics program, and it also denies Aegis the opportunity of
having accurate test correlations (see \fIaet\fP(1) for more information.)
It also denies the rest of the development team the use of the bug fix,
or worse, it allows the possibility that more than one team member will
fix the bug, wasting development effort and time.
.LP
Many configuration management systems allow you to perform a partial
check\[hy]in of a work area.  This means that you can check\[hy]in just the bug
fix, but continue to work on the unfinished portions of the functionality
you are implementing.
.LP
Because Aegis insists on atomic change sets which are known to build
and test successfully, such a partial check\[hy]in is not allowed \- because
Aegis can't know for certain that it works.
.LP
Instead, you are able to \fIclone\fP a change (see \fIaeclone\fP(1) for
more information).  This gives you a new change, and a second development
directory, with exactly the same files.  You then remove from this second
change all of the files not related to the bug fix (using \fIaecpu\fP(1),
\fIaenfu\fP(11), \fIetc\fP).  You then create a test, build, difference,
run the test, develop end, all as usual.
.LP
The original change will then need to be merged with the baseline, because
the bug fix change will have been integrated before it.  Usually this
is straight\[hy]forward, as you already have the changes (some merge tools
make this harder than others).  Often, all that is required is to merge,
and then say \[lq]\f[CW]aecpu \-unch\fP\[rq] to un\[hy]copy all files which are
(now) unchanged when compared to the current baseline.
.nh 3 "Multiple Active Branches"
.LP
Some companies have multiple branches active at the same time,
for different customers or distributions, \fIetc\fP.
.LP
They often need to make the same change to more than one branch.
Some configuration management systems allow you to check\[hy]in the same file
multiple times, once to each active branch.  Aegis does not let you do
this, because you need to convince Aegis that the change set will build
and test cleanly on each branch.  It is quite common for the change to
require non\[hy]trivial edits to work on each branch.
.nh 4 "Cloning"
.LP
Aegis instead provides two mechanisms to handle this.  The first,
and simplest to understand, is to clone the change onto each relevant branch
(rather than onto the same branch, as mentioned above for bug fixes).
Then build and test as normal.
.nh 4 "Ancestral"
.LP
The second technique is more subtle.  Perform the fix as a change to the
common ancestor of both branches.  This assumes that neither branch is
insulated against the relevant area of code, and that earlier changes
to the branch do not mask it in some way (otherwise a cross\[hy]branch merge
with the common ancestor will be needed to propagate the fix).
.nh 3 "Collaboration"
.LP
It is often the case that difficult problems are tackled by small groups
of 2 or 3 staff working together.  In order to do this, they often work
in a shared work area with group\[hy]writable or global\[hy]write permissions.
However, this tends to give security auditor heart attacks.
.LP
Aegis has several different ways to achieve the same ends, and still
not give the auditors indigestion.
.nh 4 "Change Owner"
.LP
The simplest method available is to change the ownership of a change
from one developer to the next.  A new development directory is created
for the new developer, and the source files are copied across\**.
.FS
For the technically minded: the \fIchown\fP(2) system call has semantics
which vary too widely between
.UX
variants and file\[hy]systems to be useful.
.FE
This allows a kind of serial collaboration between developers.
.nh 4 "Branch"
.LP
The other possibility is to create a branch to perform the work in,
rather than a simple change.  (A branch in Aegis is literally just
a big change, which has lots of sub\[hy]changes.)  This allows parallel
collaboration between developers.
.nh 4 "View Path Hacking"
.LP
Aegis usually provides a \[lq]view path\[rq] to the build tool.  This specifies
where to look for source files and derived files, in order to union
together the development directory, and the baseline, and the branch's
ancestors' baselines.  If you run the build by hand, rather than through
Aegis, you can add another developer's development directory to the view
path, after your own development directory, but before the baseline.
.LP
This has many of the advantages of the branch method, but none of
the safeguards.  In particular, if the other developer edits a file,
and it no longer compiles, your development directory will not, either.
.\" vim: set ts=8 sw=4 et :