Ubuntu Feisty 7.04 manual page repository

Ubuntu is a free computer operating system based on the Linux kernel. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

Provided by: aegis_4.22-2ubuntu1_i386

 

NAME

        aecstate - aegis change state file
 

SYNOPSIS

        project/info/change/[0-9]/[0-9][0-9][0-9]
 

DESCRIPTION

        A change state file is used to store information about a change.  These
        files are created and maintained by aegis.  These files should not be
        edited by humans.  These files is owned by the project owner and group.
 
        The change number is at least 3 digits, zero padded if necessary.
        (More digits will be used if a project has a thousand or more changes
        in any one release, although this is rare.)  The files are spread
        across a directory tree, 100 per subdirectory, to improve the directory
        search times, and to avoid various systems’ directory length limita‐
        tions.
 

CONTENTS

        description = string;
                This field contains a detailed description of the change.
 
        brief_description = string;
                This field contains a brief description of the change.
 
        cause = ( ... );
                This field describes the cause which motivated the change.
 
                external_bug
                        The change was created in response to a bug report from
                        outside the development team.  This repairs existing
                        functionality.
 
                external_enhancement
                        The change was created in response to an enhancement
                        request from outside the development team.  This adds
                        new functionality.
 
                external_improvement
                        The change was created in response to an improvement
                        request from outside the development team.  This
                        improves existing functionality.
 
                internal_bug
                        The change was created in response to a bug report from
                        inside the development team.  This repairs existing
                        functionality.
 
                internal_enhancement
                        The change was created in response to an enhancement
                        request from inside the development team.  This adds
                        new functionality.
 
                internal_improvement
                        The change was created in response to an improvement
                        request from inside the development team.  This
                        improves existing functionality.
 
                chain
                        This cause is where you have a fix to fix a fix; track‐
                        ing these is an interesting quality metric.
 
        test_exempt = boolean;
                This field is true if it is not necessary to test the change.
                It is, in general, desirable to test all changes, whether new
                functionality or a bug fix.  This is, however, a project man‐
                agement issue.
 
        test_baseline_exempt = boolean;
                This field is true if it is not necessary to test the change
                against the baseline before it is changed.  The test of the
                baseline is required to fail; this is to establish that the
                test has isolated the bug, and that the change has fixed that
                isolated bug.
 
        regression_test_exempt = boolean;
                This field is true if it is not necessary to perform a full
                regression test on the change.  If absent, defaults to true for
                all causes except improvements.
 
        architecture = [ string ];
                This field is a list of names of system and machine architec‐
                tures on which the change must successfully build and test.
 
        copyright_years = [ integer ];
                This field details the years in which the change was worked on.
                This field is present in trunk, branch and leaf nodes.
 
                As a change is edited, years in which the change was worked on
                accumulate in this field automatically.  Branches accumulate
                years as integrations occur.  You may need to manually edit
                this, though it should be rare.
 
        version_previous = string;
                This field records the "previous" version, mostly to simplify
                patch generation.  It is only meaningful for trunks and
                branches.  It is set automatically when a branch is started or
                integrated.
 
        attribute = [ { ... } ];
                This is a list of (name,value) pairs, defining user specified
                attributes.
 
                name = string;
                        The name of the attribute.  By convention, names which
                        start with an upper-case letter will appear in list‐
                        ings, and lower-case will not.  Attribute names are
                        case-insensitive.
 
                value = string;
                        The value of the attribute.
 
                Arguably, most change attributes which may be altered by the
                user (and some that can’t) should be of this form.  Due to an
                accident of history, this is not the case.
 
        state = ( ... );
                This field is used to describe what state the change is in.
                The state determines what operations may be performed on the
                change.
 
                awaiting_development
                        The change has been created, but has yet to be worked
                        on.
 
                being_developed
                        The change is being developed.
 
                awaiting_review
                        The change has been developed, and is waiting to be
                        review.  (Optional, controlled by the develop end
                        action project attribute.)
 
                being_reviewed
                        The change has been developed, and is being reviewed.
                        (Optional, controlled by the develop end action project
                        attribute.)
 
                awaiting_integration
                        The change has passed review, and is queued ready for
                        integration.
 
                being_integrated
                        The change is being integrated.
 
                completed
                        The change has been completed and is now part of the
                        baseline.  Changes in this state can not be reversed.
 
        given_test_exemption = boolean;
aecattr(5)) when
                the change was created.
 
        given_regression_test_exemption = boolean;
                This field is the value of regression_test_exemption (see
aecattr(5)) when the change was created.
 
        delta_number = integer;
                This field records the delta number for this change.  It is
                only present if the change is in one of the being_integrated or
                completed states.
 
        delta_uuid = string;
                This field records a universally unique identifier for this
                configuration.  It is supplements the delta_number field in
                that it is unique across all replicas of the project, whereas
                the delta number is ambiguous across replicas.  It is only
                present in the being_integrated and completed states.
 
        minimum_integration = boolean;
                This field records whether the change was placed into the
                being_integrated state using the -minimum option (or that
                option was implicitly set due to a file being removed).  It is
                only present if the change is in the being_integrated state.
 
        project_file_command_sync = integer;
                This field records the last change integrated into the project.
                If it disagrees with the project, a ’project_file_command’
                (from pconf) needs to be executed at the next build.
 
        test_time = time;
                This field records the time the last successful aegis -Test
                command was run for all architectures.  It is only present in
                the being_developed and being_integrated states.
 
        test_baseline_time = time;
                This field records the time the last successful aegis -Test
                -BaseLine command was run for all architectures.  It is only
                present in the being_developed and being_integrated states.
 
        regression_test_time = time;
                This field records the time the last successful aegis -Test
                -REGression command was run for all architectures.  It is only
                present in the being_developed and being_integrated states.
 
        build_time = time;
                This field records the last time the last successful aegis
                -Build command was run for all architectures.  It is only
                present in the being_developed and being_integrated states.
 
        architecture_times = [{ ... }];
                This field records the time of various operations for each
                variant named in the architecture field.  It is only present in
                the being_developed and being_integrated states.
 
                variant = string;
                        This field is one of the patterns named in the archi‐
                        tecture field.
 
                node = string;
                        This field is the computer on which the command was run
                        which last changed this structure.
 
                test_time = time;
                        This field records the last time the last successful
                        aegis -Test command was run for this specific pattern
                        instance.
 
                test_baseline_time = time;
                        This field records the last time the last successful
                        aegis -Test -BaseLine command was run for this specific
                        pattern instance.
 
                regression_test_time = time;
                        This field records the last time the last successful
                        aegis -Test -REGression command was run for this spe‐
                        cific pattern instance.
 
                build_time = time;
                        This field records the last time the last successful
                        aegis -Build command was run for this specific pattern
                        instance.
 
        development_directory = string;
                This field is the absolute path of a change’s development
                directory.  It is only present of the change is in a state
                between being_developed and being_integrated inclusive.
 
                However, branches are treated slightly differently to changes.
                The directory is relative to the root of the project tree, in
                order to facilitate moving the project without rewriting any of
                the database.  Note that its doesn’t point to the branch base‐
                line, but one level up; just as the project root doesn’t point
                to the trunk baseline, but rather one level up.
 
        integration_directory = string;
                This field is the absolute path of the change’s integration
                directory.  It is only present of the change is in the
                being_integrated state.
 
        history = [ { ... }, ... ];
                This field records the history of the change, in the form of
                state transitions.  The history records have the form
 
                when = time;
                        This field records the time the state transition
                        occurred.
 
                what = ( ... );
                        This field records what happened.  Valid value names
                        echo the various aegis functions.
 
                who = string;
                        This field records the user name of the user who caused
                        the state transition.
 
                why = string;
                        This field is optional.  It is a comment of some sort.
                        In the cases of review_fail and integrate_fail, this
                        field will contain why the change failed.
 
        uuid = string;
                This field provides a globally unique identifier for the change
                set, even when geographically distributed development is hap‐
                pening.
 
        branch = { ... };
                This field is only present for branches (long transactions).
 
                umask = integer;
umask(2) for more
                        information.  This value will always be OR’ed with 022,
                        because aegis is paranoid.
 
                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.
 
                        Note that the develop_end_action field may not contra‐
                        dict the developer_may_review field.  If developers may
                        not review their own work, then their changes may not
                        goto directly to the being integrated state (as this
                        means much the same thing).
 
                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
aesub(5) are available.
                        This field is optional.
 
                        Executed as: the new developer.  Current directory: the
                        development directory of the change for the new devel‐
                        oper.  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 com‐
                        mand could also be used to notify other management sys‐
                        tems, such as progress and defect tracking.  All of the
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 noti‐
                        fication will be given.  This command could also be
                        used to notify other management systems, such as
                        progress and defect tracking.  All of the substitutions
aesub(5) are available.
 
                        Executed as: the developer.  Current directory: the
                        development directory of the change.  Exit status:
                        ignored.
 
                review_begin_notify_command = string;
                        This command is used to notify that a review has begun.
                        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
aesub(5) are available.
 
                        Executed as: the reviewer.  Current directory: the
                        development directory of the change.  Exit status:
                        ignored.
 
                review_begin_undo_notify_command = string;
                        This command is used to notify that a review is no
                        longer in progress, the reviewer has withdrawn.  It
                        will probably use mail, or it could be an in-house bul‐
                        letin 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
aesub(5) are available.
 
                        Executed as: the reviewer.  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 com‐
                        mand could also be used to notify other management sys‐
                        tems, such as progress and defect tracking.  All of the
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 com‐
                        mand could also be used to notify other management sys‐
                        tems, such as progress and defect tracking.  Defaults
                        to the same action as the develop_end_notify_command
aesub(5)
                        are available.
 
                        Executed as: the reviewer.  Current directory: the
                        development directory of the change.  Exit status:
                        ignored.
 
                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 com‐
                        mand could also be used to notify other management sys‐
                        tems, such as progress and defect tracking.  All of the
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 com‐
                        mand could also be used to notify other management sys‐
                        tems, such as progress and defect tracking.  All of the
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 appro‐
                        priate 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 com‐
                        mand could also be used to notify other management sys‐
                        tems, such as progress and defect tracking.  All of the
aesub(5) are available.
 
                        Executed as: the integrator.  Current directory: the
                        development directory of the change.  Exit status:
                        ignored.
 
                default_test_exemption = boolean;
                        This field contains what to do when a change is created
                        with no test exemption specified.
 
                default_test_regression_exemption = boolean;
                        This field contains what to do when a change is created
                        with no regression test exemption specified.
 
                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 on this
                        branch to date.
 
                sub_branch = [integer];
                        The list of branches which have been created on this
                        branch to date.  This will be a subset of the above
                        (possibly empty, possibly complete, never larger).
 
                administrator = [string];
                        The list of administrators of the branch.
 
                developer = [string];
                        The list of developers of the branch.
 
                reviewer = [string];
                        The list of reviewers of the branch.
 
                integrator = [string];
                        The list of integrators of the branch.
 
                currently_integrating_change = integer;
                        The change currently being integrated.  Only one change
                        (within a branch) may be integrated at a time.  Only
                        set when an integration is in progress.
 
                default_development_directory = string;
                        The pathname of where to place new development directo‐
                        ries.  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.
 
                minimum_change_number = integer;
aenc(1), if no change
                        number is specified.  This allows the low-numbered
                        change numbers to be used for branches later in the
                        project.  Defaults to 10 if not set, may not be less
                        than 1.
 
                reuse_change_numbers = boolean;
                        This controls whether the automatically selected
aenc(1) change numbers “fill in” any gaps.  Defaults to
                        true if not set.
 
                minimum_branch_number = integer;
aenbr(1), if no branch
                        number is specified.  Defaults to 1 if not set.
 
                skip_unlucky = boolean;
                        This field may be set to true if you want to skip vari‐
                        ous unlucky numbers for changes, branches and tests.
                        Various traditions are avoided, both Eastern and West‐
                        ern.  Defaults to false if not set.
 
                compress_database = boolean;
                        This field may be set to true if you want to compress
                        the database on writing.  (It is always uncompress on
                        reading if necessary.)  Defaults to false if not set.
 
                        Unless you have an exceptionally large project, coupled
                        with fast CPUs and high network latency, there is prob‐
                        ably very little benefit in using this feature.  (The
                        database is usually less than 5% of the size of the
                        repository.)  On slow networks, however, this can
                        improve the performance of file-related commands.
 
                develop_end_action = (...);
                        This field controls the state the change enters after a
aede(1) action.
 
                        goto_being_reviewed
                                This means that the change goes from the
                                being_developed state to the being_reviewed
aerb(1) command only sends informa‐
                                tive email.
 
                        goto_awaiting_review
                                This means that the change goes from the
                                being_developed state to the awaiting_review
aerb(1) command is now mandatory.
 
                        goto_awaiting_integration
                                This means that the change goes from the
                                being_developed state into the awaiting_‐
                                integration state.  Code review is skipped
                                entirely.
 
                        Note that the develop_end_action field may not contra‐
                        dict the developer_may_review field.  If developers may
                        not review their own work, then their changes may not
                        goto directly to the being integrated state (as this
                        means much the same thing).  A contradictory setting
                        will be replaced with goto_being_reviewed.
 
    Obsolete Fields
        The following fields are only present is old projects.  They will be
        moved to an appropriate file state when the change is next modified.
aefstate(5) for more information.
 
        src = [ { ... }, ... ];
                This field is a list of all the files in the change.  The
                records have the form
 
                file_name = string;
                        This file names the file.  The name is relative to the
                        root of the baseline directory tree.
 
                uuid = string;
                        This field uniquely identifies the file for its entire
                        lifetime.  This field remains constant across file
                        renames.  The value of this field shall be formatted as
                        a valid UUID, all in lower case.
 
                action = (create, modify, remove);
                        This field describes what is being done with the file.
 
                edit_number = string;
                        This field records the edit number of the file when it
                        was added to the change (or updated using the aegis
                        -DIFFerence command).  This field is not present for
                        new files.
 
                usage = (source, config, build, test, manual_test);
                        This field describes what function the file serves.
 
                diff_time = time;
                        This field records the last time modified of the change
                        file when the last aegis -DIFFerence command was run.
                        It is only present between the being_developed and
                        being_integrated states, inclusive.  It is not present
                        for files which are being deleted.  This field is used
                        to determine if a difference has been done, and if the
                        file has been tampered with before state transitions.
 
                diff_file_time = time;
                        This field records the last time modified of the dif‐
                        ference file when the last aegis -DIFFerence command
                        was run.  It is only present between the being_devel‐
                        oped and being_integrated states, inclusive.  This
                        field is used to determine if a difference has been
                        done, and if the difference file has been tampered with
                        before state transitions.
 
                move = string;
                        To change the name of a file, a combination of deleting
                        the old name and creating the new name is used.  With
                        deleted files, this field is used to say where it went.
                        With new files, this field is used to say where it came
                        from.
        When attempting to access these fields from within the report genera‐
        tor, you need a code fragment similar to the following:
               auto ps;
               ps = project[project_name()].state;
               auto cs;
               cs = ps.branch.change[change_number()];
        All of the fields mentioned in the man page can now be accessed as mem‐
        bers of the cs variable.  For example, cs.state contains the state the
        change is in.
 
        If this change state refers to a branch, when you access a member of
        the branch.change field, you are given access to the change state data
        of that change on the branch.
 
        When you index the src field by a filename string, you may obtain
aefstate(5) for more informa‐
        tion).
aenc(1) create a new change
 
aegis(5)
                aegis file format syntax
 
aecattr(5)
                change attributes file format
 
aefstate(5)
                file state file format
 

COPYRIGHT

        aegis version
        Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
        2000, 2001, 2002, 2003, 2004, 2005, 2006 Peter Miller; All rights
        reserved.
 
        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
http://www.canb.auug.org.au/~millerp/
 

Sections

What does Ubuntu mean?
Ubuntu is an African word meaning 'Humanity to others', or 'I am what I am because of who we all are'. The Ubuntu distribution brings the spirit of Ubuntu to the software world.