.\" .\" 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 .\" . .\" .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 \&\[lq]\fIAutomatic Send\fP\[rq] section, below, for more discussion of this. .LP There are many options for customizing the e\[hy]mail message sent 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\[hy]by\[hy]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 \[lq]\fIexample.4.2\fP\[rq], 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 \[lq]super change\[rq] 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\[hy]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\[hy]mail message. If your e\[hy]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 \[lq]baseline\[rq] 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 \[lq]pull\[rq] activity, as the source may never have heard of you before. The initial baseline may arrive by e\[hy]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 a 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\[hy]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\[hy]formatted, and that there is a user\[hy]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\[hy]name and change\[hy]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\[hy]base64\fP option is used to avoid the MIME base 64 encoding, which is necessary for e\[hy]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. .\" vim: set ts=8 sw=4 et :