.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1999, 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: Howto, New project
.\"
.nh 1 "How to Create a New Project"
.LP
Before you can do anything else with Aegis, you need a project to do
it to.  The advantage of this is that each project is administered and
configured independently.
.LP
If this is your first time using Aegis, you probably want a single-user
project.  You can change the number of users later, if you ever want to
add more staff to the project.
.LP
You need to select the name with some care, as changing the project name
later is tedious.  Adding aliases, however, is simple.
.nh 2 "Single User Project"
.LP
A single suer project is one where all of the different staff roles are
filled by the same person, and a number of interlocks are disabled,
as you will see in a moment.
.LP
Unfortunately, there is no Tcl/Tk GUI for this, yet,
which makes this documentation bigger then it needs to be.
.LP
\fIDon't do anything yet!\fP
Read through all of the steps first.
.IP \(bu 2n
You may want to read the \fIaenpr\fP(1) man page for more information.
.IP \(bu 2n
The command ``\fIaenpr \fPname\fP -version -\fP'' will create the
project with no branches.  This will automatically make you (that is,
the executing user) the project administrator and the project owner.
The \fIumask\fP is remembered, too.
.IP \(bu 2n
The root of the project directory will be in your home directory,
named after the project name.
If you want something else, use the \fIaenpr --directory\fP option.
.IP \(bu 2n
The default group at the time of execution determines the file group
of the project.  Make sure the account created for the project has
the correct group.  (Even if you don't understand this, your system
administrator should.)
.IP \(bu 2n
The \fIumask\fP at the time of execution determines the group access to
the project.  Even if you usually work with a restrictive \fIumask\fP,
set it to the right one for the project before running this \fIaenpr\fP
command.
.IP \(bu 2n
For additional security, it is often \fIvery\fP useful to create a UNIX
user for each project.  You may need to consult your system administrator
for assistance with this.  It is usual to name the user and the project
the same thing, to avoid confusion.  Log in as this user to execute the
initial project creation commands; once completed \fBno one\fP will ever
login to this account again.
.IP \(bu 2n
Add the staff to the project: the ``\fIaena \fP\f[CW]your-normal-login\fP''
command adds your normal account as a project administrator.  You need
this if you are using a special project account, so that your normal
self can administer the project.
.IP \(bu 2n
At this point, log out of the special project account.
Ask the system administrator to permanently disable it.
.IP \(bu 2n
Add the rest of the staff:
the ``\fIaend \fP\f[CW]your-login\fP'' command makes you a developer,
the ``\fIaenrv \fP\f[CW]your-login\fP'' command makes you a reviewer and
the ``\fIaeni \fP\f[CW]your-login\fP'' command makes you an integrator.
.IP \(bu 2n
You need to edit the project attributes next.
The ``\fIaepa -edit\fP'' command does this.
You will be placed into a text editor,
and will see something similar to this:
.E(
description = "The \e"\fIexample\fP\e" project";
developer_may_review = false;
developer_may_integrate = false;
reviewer_may_integrate = false;
developers_may_create_changes = false;
umask = 022;
.E)
Ignore any extra stuff, you should not change it at the moment.
To get a single user project, edit the field to read
.E(
developer_may_review = true;
developer_may_integrate = true;
reviewer_may_integrate = true;
developers_may_create_changes = true;
.E)
Be extra careful to preserve the semicolons!
You may also want to change the description at this time, too.
Don't forget the closing double-quote \fIand\fP semicolon.
.IP \(bu 2n
Create the first branch now.
They inherit all staff and attributes at creation time,
which is why we worked on the trunk project first.
The command ``\fIaenbr \fP\f[CW]name\fP\fI 1\fP'' followed by
followed by ``\fIaenbr \fP\f[CW]name\fP\fI.1 0\fP'' will give you a
branch called \fIname\fP.1.0 for use wherever Aegis wants a project name.
(See the branching chapter of the User Guide for more information.)
.nh 2 "Two User Project"
.LP
Everything is done as above, except you want to project attributes to
look like this:
.E(
developer_may_review = false;
developer_may_integrate = true;
reviewer_may_integrate = true;
developers_may_create_changes = true;
.E)
This says that developers can't review their own work.
.LP
You will need to add the other person to the developer, reviewer and
integrator roles, too.
.LP
Converting a single user project to a two person project is simply editing
the project attributes to look like this later.  \fIRemember:\fP each
branch inherited its attributes when it was created \- you need to edit
the ancestor branches' project attributes too.
.nh 2 "Multi User Project"
.LP
Everything is done as above, except you want to project attributes to
look like this:
.E(
developer_may_review = false;
developer_may_integrate = false;
reviewer_may_integrate = false;
developers_may_create_changes = true;
.E)
This says that developers can't review their own work,
and reviewers can't integrate their own reviews.
This ensures the maximum number of eyes validate each change.
.LP
You will need to add the other staff to the appropriate developer,
reviewer and integrator roles.  Staff need to always be permitted all
roles: it is common for junior staff, for example, \fInot\fP to be authorised
as reviewers.
.LP
Converting a single user project to a multi-person project is simply editing
the project attributes to look like this later.  \fIRemember:\fP each
branch inherited its attributes when it was created \- you need to edit
the ancestor branches' project attributes too.
.nh 2 "Warning"
.LP
The
.I /usr/local/com/aegis/state
file contains pointers to "system" projects.
\fIPointers.\fP
Users may add their own project pointers (to their own projects)
by putting a search path into the
.I AEGIS_PATH
environment variable.
The system part is always automatically appended by \fIAegis\fP.
The default,
already set by the
.I /usr/local/lib/\%aegis/cshrc
file,
is
\fI$HOME/lib/aegis\fP.
Do not create this directory,
.I Aegis
is finicky and wants to do this itself.
.PP
Where projects reside is completely flexible,
be they system projects or user projects.
They are not kept under the
.I /usr/local/com/aegis
directory,
this directory only contains pointers.
.nh 3 "Creating Projects"
.LP
When you create a new project, the \fIfirst\fP element of the AEGIS_PATH
is used as the place to remember the project \fIpointer\fP.  This means
the project will not show up in the global project list
if you have set AEGIS_PATH to include private projects.
.LP
There are two ways to make sure that you are creating a global
project.  Either ``\fIunset AEGIS_PATH\fP'' immediately before
using the ``\fIaenpr\fP'' command, or use the ``\f[CW]--library\fP
\fI/usr/local/com/aegis\fP'' option of the \fIaenpr\fP command.
.nh 3 "Web Visibility"
.LP
If you have a Web server, and the \f(CWaegis.cgi\fP was installed, you
can set its \fIAEGIS_PATH\fP environment variable, if you want it to be
able to see more projects than just the global projects.  You do this by
creating a \fI/usr/local/lib/\%aegis.cgi.conf\fP file (there isn't one,
by default) and setting the \fIAEGIS_PATH\fP environment variable in it.
This is a fragment of Bourne shell script, not just the name.
.nh 2 "Changing The Project Owner"
.LP
Typically, when folks try Aegis for the first time, they don't worry about
having a separate user for their projects.  However, once things are
ticking along, it is less and less attractive to toss it all and start
again cleanly.  So, now you need to change the project owner from the
user who started the Aegis evaluation to the unique project user account.
.IP 1. 3n
You need to be \fIroot\fP to perform this procedure.
.IP 2. 3n
Create the user account.  It doesn't need to work to login, so the
password can be disabled.  You probably want to arrange to have this
user's email forwarded somewhere sensible (maybe see the Distributed
Development chapter of the User Guide).
.IP 3. 3n
The owner of the project is taken from the owner of the project directory
tree, so this is what needs to be changed.  Go to the root of the project
tree - the directory which appears in the ``\fIael projects\fP'' listing.
This isn't the trunk baseline, but the directory above it (you will see
\fIinfo\fP, \fIhistory\fP and \fIbaseline\fP sub-directories).
.IP 4. 3n
Use the command
.E(
chown -R \fIusername\fP .
.E)
to change the ownership of this directory, and all files and
sub-directories below it.  Insert the username of the account you created
in step 2.  (You need the \fBdot\fP on the end of the command, its not
mere punctuation.)
.PP
There is no need to change the owner of any active changes,
or any other change attributes.