.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-2000, 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/>.
.\"
.bp
.if t .2C
.nh 1 "The Project Attributes"
.LP
The project attributes are manipulated using the
\fIaepa\fP(1)
command.
This command reads a project attributes file to set the project attributes.
This file can be thought of as having several sections,
each of which will be covered by this chapter.
You should see the
\fIaepattr\fP(5)
manual entry for more details.
.nh 2 "Description and Access"
.LP
The
\fIdescription\fP
field is a string which contains
a description of the project.
Large amounts of prose are not required;
a single line is sufficient.
.LP
The
\fIdefault_development_directory\dP
field is a string which contains
the pathname of where to place new development directories.
The pathname must be absolute.
This field is only
consulted if the
\fIuconf\fP(5)
field of the same name is not set.
Defaults to
\fI$HOME\fP.
.LP
The
\fIumask\fP
field is an integer which is set to the
file permission mode mask.
See
\fIumask\fP(2)
for more information.
This value will always be OR'ed with 022,
because aegis is paranoid.
.nh 2 "Notification Commands"
.LP
The
\fIdevelop_end_notify_command\fP
field is a string which contains a command to be used to
notify that a change requires reviewing.
All of the substitutions described in
\fIaesub\fP(5)
are available.
This field is optional, if it is not specified no notification will be issued.
This command could also be used to notify other management systems,
such as progress and defect tracking,
in addition to notifying users.
.LP
The
\fIdevelop_end_undo_notify_command\fP
field is a string containing a command used to
notify that a change has been withdrawn from review
for further development.
All of the substitutions described in
\fIaesub\fP(5)
are available.
This field is optional, if it is not specified no notification will be issued.
This command could also be used to notify other management systems,
such as progress and defect tracking,
in addition to notifying users.
.LP
The
\fIreview_pass_notify_command\fP
field is a string containing the command to
notify that the review has passed.
All of the substitutions described in
\fIaesub\fP(5)
are available.
This field is optional, if it is not specified no notification will be issued.
This command could also be used to notify other management systems,
such as progress and defect tracking,
in addition to notifying users.
.LP
The
\fIreview_pass_undo_notify_command\fP
field is a string containing the command to
notify that a review pass has has been rescinded.
All of the substitutions described in
\fIaesub\fP(5)
are available.
This field is optional, and defaults to the
\fIdevelop_end_notify_command\fP
field if not specified.
If neither is specified, no notification will be issued.
This command could also be used to notify other management systems,
such as progress and defect tracking,
in addition to notifying users.
.LP
The
\fIreview_fail_notify_command\fP
field is a string containing the command to
notify that the review has failed.
All of the substitutions described in
\fIaesub\fP(5)
are available.
This field is optional, if it is not specified no notification will be issued.
This command could also be used to notify other management systems,
such as progress and defect tracking,
in addition to notifying users.
.LP
The
\fIintegrate_pass_notify_command\fP
field is a string containing the command to
notify that the integration has passed.
All of the substitutions described in
\fIaesub\fP(5)
are available.
This field is optional, if it is not specified no notification will be issued.
This command could also be used to notify other management systems,
such as progress and defect tracking,
in addition to notifying users.
.LP
The
\fIintegrate_fail_notify_command\fP
field is a string containing the command to
notify that the integration has failed.
All of the substitutions described in
\fIaesub\fP(5)
are available.
This field is optional, if it is not specified no notification will be issued.
This command could also be used to notify other management systems,
such as progress and defect tracking,
in addition to notifying users.
.nh 3 "Notification by email"
.LP
The aegis command is distributed with a set of shell scripts to
perform these notifications by email.
They are installed into the
\fI\*(L)\fP
directory, by default;
the actual installed directory at your site is available as the
\fI${DATa_DIRectory}\fP
substitution.
The entries in the project attribute file look like this:
.E(
develop_end_notify_command =
  "$sh $datadir/de.sh $project $change";
develop_end_undo_notify_command =
  "$sh $datadir/deu.sh $project $change";
review_pass_notify_command =
  "$sh $datadir/rp.sh $project $change \e
  $developer $reviewer";
review_pass_undo_notify_command =
  "$sh $datadir/rpu.sh $project $change \e
  $developer";
review_fail_notify_command =
  "$sh $datadir/rf.sh $project $change \e
  $developer $reviewer";
integrate_pass_notify_command =
  "$sh $datadir/ip.sh $project $change \e
  $developer $reviewer $integrator";
integrate_fail_notify_command =
  "$sh $datadir/if.sh $project $change \e
  $developer $reviewer $integrator";
.E)
.LP
Please note: the exit status of all these commands will be ignored.
.nh 3 "Notification by USENET"
.LP
The aegis command is distributed with a set of shell scripts to
perform these notifications by USENET.
They are installed into the
\fI\*(L)\fP
directory, by default;
the actual installed directory at your site is available as the
\fI${DATa_DIRectory}\fP
substitution.
The entries in the project attribute file look like this:
.E(
develop_end_notify_command =
  "$sh $datadir/de.inews.sh $p $c alt.$p";
develop_end_undo_notify_command =
  "$sh $datadir/deu.inews.sh $p $c alt.$p";
review_pass_notify_command =
  "$sh $datadir/rp.inews.sh $p $c alt.$p";
review_pass_undo_notify_command =
  "$sh $datadir/rpu.inews.sh $p $c alt.$p";
review_fail_notify_command =
  "$sh $datadir/rf.inews.sh $p $c alt.$p";
integrate_pass_notify_command =
  "$sh $datadir/ip.inews.sh $p $c alt.$p";
integrate_fail_notify_command =
  "$sh $datadir/if.inews.sh $p $c alt.$p";
.E)
.LP
The last argument to each command is the newsgroup to post the article in,
you may want to use some other group.
Note that "$p" is an abbreviation for "$project"
and "$c" is an abbreviation for "$change".
.nh 2 "Exemption Controls"
.LP
The
\fIdeveloper_may_review\fP
field is a boolean.
If this field is true,
then a developer may review her own change.
This is probably only a good idea for projects of less than 3 people.
The idea is for as many people as possible to critically examine a change.
.LP
The
\fIdeveloper_may_integrate\fP
field is a boolean.
If this field is true,
then a developer may integrate her own change.
This is probably only a good idea for projects of less than 3 people.
The idea is for as many people as possible to critically examine a change.
.LP
The
\fIreviewer_may_integrate\fP
field is a boolean.
If this field is true,
then a reviewer may integrate a change she reviewed.
This is probably only a good idea for projects of less than 3 people.
The idea is for as many people as possible to critically examine a change.
.LP
The
\fIdevelopers_may_create_changes\fP
field is a boolean.
If this field is true then developers may create changes,
in addition to administrators.
This tends to be a very useful thing,
since developers find most of the bugs.
.LP
The
\fIdefault_test_exemption\fP
field is a boolean.
This field contains what to do when a change is created with
no test exemption specified.
The default is "false", i.e. no testing exemption,
tests must be provided.
.LP
This kind of blanket exemption should only be set when
a project has absolutely no functionality available from the command line;
examples include X11 programs.
The program could possibly be improved by providing access to
the functionality from the command line,
thus allowing tests to be written.
.nh 3 "One Person Projects"
.LP
The entries in the project attributes file for a
one person project look like this:
.E(
developer_may_review = true;
developer_may_integrate = true;
reviewer_may_integrate = true;
developers_may_create_changes = true;
.E)
.LP
All of the staff roles
(administrator, developer, reviewer and integrator)
are all set to be the same user.
.nh 3 "Two Person Projects"
.LP
A two person project has the opportunity for each to review the other's work.
.LP
The entries in the project attributes file for a
two person project look like this:
.E(
developer_may_review = false;
developer_may_integrate = true;
reviewer_may_integrate = true;
developers_may_create_changes = true;
.E)
.LP
All of the staff roles
(developer, reviewer and integrator)
are all set to allow both users.
.nh 3 "Larger Projects"
.LP
Once you have 3 or more staff on a project,
you can assign all of the roles to separate people.
The idea is for the greatest number of eyes to see each change
and detect flaws before they reach the baseline.
.LP
The entries in the project attributes file for a
three person project look like this:
.E(
developer_may_review = false;
developer_may_integrate = false;
reviewer_may_integrate = false;
developers_may_create_changes = true;
.E)
.LP
For smaller teams,
everyone may be a reviewer.
As the teams get larger,
the more experienced staff are often the reviewers,
rather than everyone.
.nh 3 "RSS Feeds"
.LP
Aegis has the ability to publish RSS 2.0 items to an RSS channel when
changesets transition to a new state.  This is an optional feature that
must be enabled and configured via the project\[hy]specific attributes.
.LP
Project administrators can configure each change of state to cause an RSS
item to be added to a specified RSS channel.  Each transition is
individually controlled, allowing each transition to be recorded in
separate channels, or all transitions in the same channel, or some
combination thereof.
.LP
Generating RSS items for particular state transitions is enabled by the
\fIrss:feedfilename\fP
project\[hy]specific attibute.  The format of this attribute is:
.E(
name = "rss:feedfilename\-<filename>";
value = "<state> [<state> <state>]";
.E)
The
\fIname\fP
part of this attribute includes a
\fIfilename,\fP
which is the name of the RSS feed file (channel) to which the item is to
be added.  The
\fIvalue\fP
part of the attribute is a space\[hy]separated list of states that will cause
an RSS item to be added to the specified file.  For example,
.E(
name = "rss:feedfilename\-foo.xml";
value = "awaiting_review
         awaiting_integration";
.E)
will cause items to be added to the channel stored in the file "foo.xml"
when a changeset transitions
\fIinto\fP
the awaiting_review and awaiting_integration states.
.LP
The channel description can be specified using the
\fIrss:feeddescription\fP
attribute.  The format of this attribute is:
.E(
name = "rss:feeddescription\-<filenane>";
value = "<Some description>";
.E)
For example,
.E(
name = "rss:feeddescription\-foo.xml";
value = "This is a description";
.E)
will cause the <description> sub\[hy]element of the <channel> element stored in
the file foo.xml to have the value
"\fIThis is a description\fP".
If this attribute is not used, the default description is:
"\fIFeed of changes in state...\fP"
.LP
The channel title can be specified using the
\fIrss:feedtitle\fP
attribute.  The format of this attribute is:
.E(
name = "rss:feedtitle\-<filename>";
value = <Some title>;
.E)
For example,
.E(
name = "rss:feedtitle\-foo.xml";
value = "This is a title";
.E)
will cause the <title> sub\[hy]element of the <channel> element stored in the
file foo.xml to have the value
"\fPProject ...: This is a title\fP"
The title will always start with the word "Project" and the project name.
If this attribute is supplied, this default title is appended with the
test provided.
.LP
The channel language can be specified using the
\fIrss:feedlanguage\fP
attribute.  The format of this attribute is:
.E(
name = "rss:feedlanguage\-\fIfilename\fP";
value = "\fIlanguage\fP";
.E)
For example,
.E(
name = "rss:feedlanguage\-foo.xml";
value = "en\-AU";
.E)
will cause the <language> sub\[hy]element of the <channel> element stored in
the file foo.xml to have the value
\fIen\[hy]AU\fP
If not specified, the default value of the language sub\[hy]element is
"en\[hy]US".
.nh 4 "Serving RSS Channels"
.LP
aeget is able to serve up RSS channels, with an appropriate URL.  An example
URL is
.E(
http://somehost/cgi\-bin/aeget/proj.1.0/?rss+foo.xml
.E)
The key aspect of the URL shown is the
"\fI?rss+foo.xml\fP"
modifier.
"\fIfoo.xml\fP"
should obviously be replaced with the name of your RSS channel feed
(that is, the filename specified with the
"\fIrss:feedfilename\fP"
project\[hy]specified attribute(s).
.LP
In order to read the RSS channels, it is recommended to point your RSS
aggregator of choice to the appropriate URL.  In order to make determining
the URL easy, aeget will also place "RSS" icons next to the individual state
links on the main project web page (\fI"proj.1.0/?menu"\fP)
if there is an RSS channel configured to include that changeset state.
.nh 4 "Links in RSS Channels"
.LP
Links within RSS feed files are stored using a placeholder ("@@SCRIPTNAME@@")
instead of the serving script in URLs.  This is done because the code that
knows about hte URL of a particular installation is encapsulated within aeget.
.LP
The placeholder is replaced with the real scriptname when the file is served
by aeget.
.\" vim: set ts=8 sw=4 et :