Provided by: aegis_4.24.3-2_i386 bug

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.

CONTENTS

        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.

SEE ALSO

        aenpr(1)
                create a new project

        aegis(5)
                aegis file format syntax

        aepattr(5)
                project attributes file format

        aecstate(5)
                change state file

        aefstate(5)
                file state file

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/