Provided by: aegis_4.24.3-3_amd64 
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 limitations.
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; tracking 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 management 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 architectures 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 listings, 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;
This field is the value of test_exemption (see 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 architecture 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 specific 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 baseline, 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 happening.
branch = { ... };
This field is only present for branches (long transactions).
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.
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 contradict 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
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_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 described by 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 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_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.
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 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_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 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.
minimum_change_number = integer;
The minimum change number for 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;
The minimum branch number for 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 various unlucky numbers
for changes, branches and tests. Various traditions are avoided, both
Eastern and Western. 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 probably 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 successful
aede(1) action.
goto_being_reviewed
This means that the change goes from the being_developed state to
the being_reviewed state. The aerb(1) command only sends
informative email.
goto_awaiting_review
This means that the change goes from the being_developed state to
the awaiting_review state. The 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 contradict 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. See 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 difference file when the
last aegis -DIFFerence command was run. It is only present between the
being_developed 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.
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;
auto cs;
cs = ps.branch.change[change_number()];
All of the fields mentioned in the man page can now be accessed as members 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 access the the relevant
file state (see aefstate(5) for more information).
SEE ALSO
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 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/