.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1999 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, Geographically Distributed Development, Manual Operation
.\"
.nh 2 "Manual Operation"
.LP
This section describes how to use \fIaedist\fP manually,
in order to send and receive change sets.
.nh 3 "Manual Send"
.LP
In order to send a change set to another site, it must be packaged in a
form which captures all of the change's attributes and the contents of
the change's files.  This package must be compressed and encoded in a form
which will survive the various mail transport agents it must pass through,
and then given to the local mail transport agent.
This is done by a single command
.E(
\f(CB%\fP aedist -send -c \fInumber\fP | \e
  mail joe.blow@example.com
\f(CB%\fP
.E)
.LP
All of the usual Aegis command line options are available,
so you could specify the project on the command line if you needed to.
.LP
This command will send the sources from the development directory, if the
change is not yet completed.  This is useful for collaboration between
developers, but it isn't reviewed and integrated, so beware.
.LP
It is more usual to send a change which has been completed.  In this case
the version of the file which was committed is sent.  If necessary, the
history files will be consulted to reconstruct this information.  See the
\&``\fIAutomatic Send\fP'' section, below, for more discussion of this.
.LP
There are many options for customizing the e-mail message set to
\&\f(CWjoe.blow@example.com\fP, see \fIaedist\fP(1) for more information.
.nh 3 "Sending Baselines"
.LP
In order to send the entire contents of the
repository to someone, you use a very similar command:
.E(
\f(CB%\fP aedist -send -baseline | \e
  mail joe.blow@example.com
\f(CB%\fP
.E)
.LP
This can be a very large change set, because it is all files of the project.
.nh 3 "Sending Branches"
.LP
There are times when remote developers are not interested in a
blow-by-blow update of your repository.  Instead they want to have
updates from time to time.  In order to send them the current state of
your active development branch, in this example ``\fIexample.4.2\fP'',
you would use a command of the form
.E(
\f(CB%\fP aedist -send -p example.4 -c 2 | \e
  mail joe.blow@example.com
\f(CB%\fP
.E)
Notice how the correspondence between branches and change sets is
exploited.  The baseline of a branch is the development directory of the
``super change'' is represents.
.LP
Branch change sets like this are smaller than whole baselines, because
they include only the files altered by this branch, rather then the
state of every file in the project.
.nh 3 "Manual Receive"
.LP
The simplest form of receiving a change set is to save it from your
e-mail program into a file, and then
.E(
\f(CB%\fP aedist -receive -file \fIfilename\fP
\&\fI...lots of information...\fP
\f(CB%\fP
.E)
where \fIfilename\fP is where you saved the e-mail message.
If your e-mail program is able to write to a pipe, you can use a simpler form.
This example uses the Rand Mail Handler's \fIshow\fP(1) command:
.E(
\f(CB%\fP show | aedist -receive
\&\fI...lots of information...\fP
\f(CB%\fP
.E)
.LP
Each of these examples assumes that you have used the same project name
locally as that of the sender (it's stored in the package).  If this
isn't the case, you will need to use the \f(CW\-project\fP option to
tell \fIaedist\fP which project to apply the change to.
.LP
The actions performed by \fIaedist\fP on receive are not quite a
mirror of what it does on send.  In particular, send usually extracts
its information from the repository, but receive \fBdoes not\fP put
the change set directly into the repository.
.LP
On receipt of a change set, \fIaedist\fP creates a new change with its
own development directory, and unpacks the change set into it, in much
the same way as a change would normally be performed by a developer.
(Indeed, the receiver must be an authorized developer.)
.LP
Once the change is unpacked, it goes through the usual development
cycle of build, difference and test.  If any portion of this fails,
\fIaedist\fP will stop with a suitable error message.
If all goes well, development of the change will end,
and it will be left in the \fIbeing reviewed\fP state.
.LP
At this point, a local reviewer must examine the change,
and it proceeds through the change integration process as normal.
.LP
If there is a problem with the change, it can be dealt with as you would
with any other defective change \- by developing it some more.  Or you
can email the sender telling them the problem and use \fIaedbu\fP(1)
and \fIaencu\fP(1) to entirely discard the change.
.nh 3 "Getting Started"
.LP
In order to receive a change, you must have a project to receive it into.
Also, changes tend to be the \fIdifference\fP between an existing
repository and what it is to become.  You need some way to get the
starting point of the differences before you can apply any differences.
This section describes one way of doing this.
.LP
You start by creating a normal Aegis project in the usual way.  That is
covered earlier in this User Guide.  It helps greatly if you give your
local project exactly the same name as the remote project.  It doesn't
need the same pathname for the project directory, just the same project
name.
.LP
Once you have this project created, request the remote repository send
you a ``baseline'' change, as described above.  Once you have received
this, and it is integrated successfully, you are ready to receive and
apply change sets.  This is an inherently ``pull'' activity, as the
source may never have heard of you before.  The initial baseline may
arrive by e-mail, or floppy disk, or you may retrieve it from the web,
it all depends how the project is being managed.
.LP
You will be warned about "potential trojan horse" files in the baseline
change set.  This is normal, because you are receiving all project
configurations file, build files and test files.  All of these contain
executable commands \fIthat will be executed\fP.  Caveat emptor.
Make sure you trust the source.
.nh 2 "Sneaker Net"
.LP
Another common method of transporting data, sometimes quite large amount
of it, is to write it onto transportable media and carry it.
.LP
To write a change set onto a floppy, you would use commands such as
.E(
\f(CB%\fP mount /mnt/floppy
\f(CB%\fP aedist -send -no-base64 \e
  -o /mnt/floppy/\fIchange.set\fP
\f(CB%\fP umount /mnt/floppy
\f(CB%\fP
.E)
The above command assumes the floppy is pre-formatted, and that there
is a user-permitting line in the \fI/etc/fstab\fP file, as is common for
many Linux distributions.  The \fIchange.set\fP can be any filename you
like, but is usually project-name and change-number related.
.LP
It takes a very sizable change set to fail to fit on a 1.44MB floppy,
because they are compressed (and change sets exceeding 8MB of source
are rare, even for huge projects).  The \f(CW-no-base64\fP option is
used to avoid the MIME base 64 encoding, which is necessary for e-mail,
not not necessary in this case.  The receive side will automatically
figure out there is no MIME base 64 encoding.
.LP
Reading the change set is just as simple, as it closely follows the
other commands for receiving commands sets.
.E(
\f(CB%\fP mount /mnt/floppy
\f(CB%\fP aedist -rec -f /mnt/floppy/\fIchange.set\fP
\&\fI...lots of output...\fP
\f(CB%\fP umount /mnt/floppy
\f(CB%\fP
.E)
This technique will work for any of the disks available these days
including floppies, Zip, Jaz, \fIetc\fP.