Ubuntu Manpage: aepstate - aegis project state file

NAME

        aepstate - aegis project state file

SYNOPSIS

        project/info/state

DESCRIPTION

        The project/info/state file is used to store state information about a project.

        This file is maintained by aegis and thus should not be edited by humans.

next_test_number = integer;
Each test is numbered uniquely across all branches of the project. The name is
of the form t[0-9][0-9][0-9][0-9][am].sh ('a' for automatic and 'm' for manual.)

Almost Obsolete Fields
The following fields are obsolete. They will persist until the next aenrls(1), and the
new project so generated will use them to define its default branching.

version_major = integer;
The major version number of this release of the project. Always one or more.

version_minor = integer;
The minor version number of this release of the project. Always zero or more.

Obsolete Fields
The following fields are obsolete. They are only present in projects which have yet to
be converted to the new branch format. When Aegis sees them, they will be moved into the
"trunk" transaction.

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

owner_name = string;
This field is ignored.

group_name = string;
This field is ignored.

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

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

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

developers_may_create_changes = boolean;
This field is true if developers may created changes, in addition to
administrators. This tends to be a very useful thing, since developers find most
of the bugs.

forced_develop_begin_notify_command = string;
This command is used to notify a developer that a change requires developing; it
is issued when a project administrator uses an aedb -User command to force
development of a change by a specific user. All of the substitutions described
in aesub(5) are available. This field is optional.

Executed as: the new developer. Current directory: the development directory of
the change for the new developer. Exit status: ignored.

develop_end_notify_command = string;
This command is used to notify that a change is ready for review. It will
probably use mail, or it could be an in-house bulletin board. This field is
optional, if not present no notification will be given. This command could also
be used to notify other management systems, such as progress and defect tracking.
All of the substitutions described by aesub(5) are available.

Executed as: the developer. Current directory: the development directory of the
change. Exit status: ignored.

develop_end_undo_notify_command = string;
This command is used to notify that a change had been withdrawn from review for
further development. It will probably use mail, or it could be an in-house
bulletin board. This field is optional, if not present no notification will be
given. This command could also be used to notify other management systems, such
as progress and defect tracking. All of the substitutions described by aesub(5)
are available.

Executed as: the developer. Current directory: the development directory of the
change. Exit status: ignored.

review_pass_notify_command = string;
This command is used to notify that a review has passed. It will probably use
mail, or it could be an in-house bulletin board. This field is optional, if not
present no notification will be given. This command could also be used to notify
other management systems, such as progress and defect tracking. All of the
substitutions described by aesub(5) are available.

Executed as: the reviewer. Current directory: the development directory of the
change. Exit status: ignored.

review_pass_undo_notify_command = string;
This command is used to notify that a review has passed. It will probably use
mail, or it could be an in-house bulletin board. This field is optional, if not
present no notification will be given. This command could also be used to notify
other management systems, such as progress and defect tracking. Defaults to the
same action as the develop_end_notify_command field. All of the substitutions
described by aesub(5) are available.

review_fail_notify_command = string;
This command is used to notify that a review has failed. It will probably use
mail, or it could be an in-house bulletin board. This field is optional, if not
present no notification will be given. This command could also be used to notify
other management systems, such as progress and defect tracking. All of the
substitutions described by aesub(5) are available.

Executed as: the reviewer. Current directory: the development directory of the
change. Exit status: ignored.

integrate_pass_notify_command = string;
This command is used to notify that an integration has passed. It will probably
use mail, or it could be an in-house bulletin board. This field is optional, if
not present no notification will be given. This command could also be used to
notify other management systems, such as progress and defect tracking. All of
the substitutions described by aesub(5) are available.

Some compilers bury absolute path names into object files and executables. The
renaming of the integration directory to become the new baseline breaks these
paths. This command is passed an environment variable called AEGIS_INTEGRATION_‐
DIRECTORY so that the appropriate symlink may be placed, if desired.

Executed as: the project owner. Current directory: the new project baseline.
Exit status: ignored.

integrate_fail_notify_command = string;
This command is used to notify that an integration has failed. It will probably
use mail, or it could be an in-house bulletin board. This field is optional, if
not present no notification will be given. This command could also be used to
notify other management systems, such as progress and defect tracking. All of
the substitutions described by aesub(5) are available.

Executed as: the integrator. Current directory: the development directory of the
change. Exit status: ignored.

default_development_directory = string;
The pathname of where to place new development directories. The pathname must be
absolute. This field is only consulted if the field of the same name in the user
configuration file is not set.

umask = integer;
File permission mode mask. See umask(2) for more information. This value will
always be OR'ed with 022, because aegis is paranoid.

default_test_exemption = boolean;
This field contains what to do when a change is created with no test exemption
specified.

copyright_years = [ integer ];
This field contains a list of copyright years, for use in copyright notices, etc.
It is updated each integrate_begin, if necessary, to include the current year.
Available as the ${Copyright_Years} substitution, and included in the version
listing.

next_change_number = integer;
Changes are numbered sequentially from one. This field records the next unused
change number.

next_delta_number = integer;
Deltas are numbered sequentially from one. This field records the next unused
delta number.

src = [ { ... } ];
If you are writing a report, see aefstate(5) for the current documentation for
this field. This field is a list of files in the project. Each list item has
the form:

file_name = string;
The name of the file, relative to the baseline.

usage = (source, config, build, test, manual_test);
What the file is for.

edit_number = string;
The edit number of the file.

locked_by = integer;
The change which locked this file.
Caveat: this field is redundant, you can figure it out by scanning all of
he change files. Having it here is very convenient, even though it means
multiple updates.

about_to_be_created_by = integer;
The change which is about to create this file for the first time. Same
caveat as above.

deleted_by = integer;
The change which last deleted this file. We never throw them away,
because (a) it may be created again, and more important (b) we need it to
recreate earlier deltas.

history = [{ ... }];
This field contains a history of integrations for the project. Updated by each
successful 'aegis -Integrate_Pass' command.

delta_number = integer;
The delta number of the integration.

change_number = integer;
The number of the change which was integrated.

name = [ string ];
The names by which this delta is known.

change = [integer];
The list of changes which have been created to date.

administrator = [string];
The list of administrators of the project.

developer = [string];
The list of developers of the project.

reviewer = [string];
The list of reviewers of the project.

integrator = [string];
The list of integrators of the project.

currently_integrating_change = integer;
The change currently being integrated. Only one change (within a project) may be
integrated at a time. Only set when an integration is in progress.

version_major = integer;
The major version number of this release of the project. Always one or more.

version_minor = integer;
The minor version number of this release of the project. Always zero or more.

version_previous = string;
The version number this project was derived from. This is of most use when
producing "patch" files.

WRITING REPORT SCRIPTS

        When attempting to access these fields from within the report generator, you need a code
        fragment similar to the following:
                auto ps;
                ps = project[project_name()].state;
        All of the fields mentioned in the man page can now be accessed as members of the ps
        variable.

        When you access the branch field, you obtain access to the change state of the branch.
        Even the trunk has one of these, it just doesn't have a number, and it is perpetually
        being developed.

        When you index the branch.change field by a change number, you obtain access to the
        change state of that change.

        When you index the branch.src field by a filename string, you may obtain access the the
        relevant project file state (see aefstate(5) for more information).

        In addition to the above fields, the report generator inserts a name field containing the
        project name, and a directory field containing the project directory path.

COPYRIGHT

        aegis version 4.24.3.D001
        Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
        2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Peter Miller

        The aegis program comes with ABSOLUTELY NO WARRANTY; for details use the 'aegis -VERSion
        License' command.  This is free software and you are welcome to redistribute it under
        certain conditions; for details use the 'aegis -VERSion License' command.

AUTHOR

        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/