Chapter 7. The Project Attributes

Table of Contents

1. Description and Access
2. Notification Commands
2.1. Notification by email
2.2. Notification by USENET
3. Exemption Controls
3.1. One Person Projects
3.2. Two Person Projects
3.3. Larger Projects
3.4. RSS Feeds

The project attributes are manipulated using the aepa(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 aepattr(5) manual entry for more details.

1. Description and Access

The description field is a string which contains a description of the project. Large amounts of prose are not required; a single line is sufficient.

The default_development_directory 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 uconf(5) field of the same name is not set. Defaults to $HOME.

The umask field is an integer which is set to the file permission mode mask. See umask(2) for more information. This value will always be OR'ed with 022, because aegis is paranoid.

2. Notification Commands

The develop_end_notify_command field is a string which contains a command to be used to notify that a change requires reviewing. All of the substitutions described in aesub(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.

The develop_end_undo_notify_command 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 aesub(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.

The review_pass_notify_command field is a string containing the command to notify that the review has passed. All of the substitutions described in aesub(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.

The review_pass_undo_notify_command field is a string containing the command to notify that a review pass has has been rescinded. All of the substitutions described in aesub(5) are available. This field is optional, and defaults to the develop_end_notify_command 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.

The review_fail_notify_command field is a string containing the command to notify that the review has failed. All of the substitutions described in aesub(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.

The integrate_pass_notify_command field is a string containing the command to notify that the integration has passed. All of the substitutions described in aesub(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.

The integrate_fail_notify_command field is a string containing the command to notify that the integration has failed. All of the substitutions described in aesub(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.

2.1. Notification by email

The aegis command is distributed with a set of shell scripts to perform these notifications by email. They are installed into the /opt/aegis/lib directory, by default; the actual installed directory at your site is available as the ${DATa_DIRectory} substitution. The entries in the project attribute file look like this:

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 \
  $developer $reviewer";
review_pass_undo_notify_command =
  "$sh $datadir/rpu.sh $project $change \
  $developer";
review_fail_notify_command =
  "$sh $datadir/rf.sh $project $change \
  $developer $reviewer";
integrate_pass_notify_command =
  "$sh $datadir/ip.sh $project $change \
  $developer $reviewer $integrator";
integrate_fail_notify_command =
  "$sh $datadir/if.sh $project $change \
  $developer $reviewer $integrator";

Please note: the exit status of all these commands will be ignored.

2.2. Notification by USENET

The aegis command is distributed with a set of shell scripts to perform these notifications by USENET. They are installed into the /opt/aegis/lib directory, by default; the actual installed directory at your site is available as the ${DATa_DIRectory} substitution. The entries in the project attribute file look like this:

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";

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".

3. Exemption Controls

The developer_may_review 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.

The developer_may_integrate 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.

The reviewer_may_integrate 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.

The developers_may_create_changes 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.

The default_test_exemption 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.

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.

3.1. One Person Projects

The entries in the project attributes file for a one person project look like this:

developer_may_review = true;
developer_may_integrate = true;
reviewer_may_integrate = true;
developers_may_create_changes = true;

All of the staff roles (administrator, developer, reviewer and integrator) are all set to be the same user.

3.2. Two Person Projects

A two person project has the opportunity for each to review the other's work.

The entries in the project attributes file for a two person project look like this:

developer_may_review = false;
developer_may_integrate = true;
reviewer_may_integrate = true;
developers_may_create_changes = true;

All of the staff roles (developer, reviewer and integrator) are all set to allow both users.

3.3. Larger Projects

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.

The entries in the project attributes file for a three person project look like this:

developer_may_review = false;
developer_may_integrate = false;
reviewer_may_integrate = false;
developers_may_create_changes = true;

For smaller teams, everyone may be a reviewer. As the teams get larger, the more experienced staff are often the reviewers, rather than everyone.

3.4. RSS Feeds

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-specific attributes.

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.

Generating RSS items for particular state transitions is enabled by the rss:feedfilename project-specific attibute. The format of this attribute is:

name = "rss:feedfilename-<filename>";
value = "<state> [<state> <state>]";

The name part of this attribute includes a filename, which is the name of the RSS feed file (channel) to which the item is to be added. The value part of the attribute is a space-separated list of states that will cause an RSS item to be added to the specified file. For example,

name = "rss:feedfilename-foo.xml";
value = "awaiting_review
         awaiting_integration";

will cause items to be added to the channel stored in the file "foo.xml" when a changeset transitions into the awaiting_review and awaiting_integration states.

The channel description can be specified using the rss:feeddescription attribute. The format of this attribute is:

name = "rss:feeddescription-<filenane>";
value = "<Some description>";

For example,

name = "rss:feeddescription-foo.xml";
value = "This is a description";

will cause the <description> sub-element of the <channel> element stored in the file foo.xml to have the value "This is a description". If this attribute is not used, the default description is: "Feed of changes in state..."

The channel title can be specified using the rss:feedtitle attribute. The format of this attribute is:

name = "rss:feedtitle-<filename>";
value = <Some title>;

For example,

name = "rss:feedtitle-foo.xml";
value = "This is a title";

will cause the <title> sub-element of the <channel> element stored in the file foo.xml to have the value "Project ...: This is a title" 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.

The channel language can be specified using the rss:feedlanguage attribute. The format of this attribute is:

name = "rss:feedlanguage-filename";
value = "language";

For example,

name = "rss:feedlanguage-foo.xml";
value = "en-AU";

will cause the <language> sub-element of the <channel> element stored in the file foo.xml to have the value en-AU If not specified, the default value of the language sub-element is "en-US".

3.4.1. Serving RSS Channels

aeget is able to serve up RSS channels, with an appropriate URL. An example URL is

http://somehost/cgi-bin/aeget/proj.1.0/?rss+foo.xml

The key aspect of the URL shown is the "?rss+foo.xml" modifier. "foo.xml" should obviously be replaced with the name of your RSS channel feed (that is, the filename specified with the "rss:feedfilename" project-specified attribute(s).

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 ("proj.1.0/?menu") if there is an RSS channel configured to include that changeset state.

3.4.2. Links in RSS Channels

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.

The placeholder is replaced with the real scriptname when the file is served by aeget.