table of contents
other versions
- jessie 4.24.3-3
aecstate(5) | File Formats Manual | aecstate(5) |
NAME¶
aecstate - aegis change state fileSYNOPSIS¶
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;
-
- brief_description = string;
-
- cause = ( ... );
-
- external_bug
-
- external_enhancement
-
- external_improvement
-
- internal_bug
-
- internal_enhancement
-
- internal_improvement
-
- chain
-
- test_exempt = boolean;
-
- test_baseline_exempt = boolean;
-
- regression_test_exempt = boolean;
-
- architecture = [ string ];
-
- 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.
- state = ( ... );
-
- awaiting_development
-
- being_developed
-
- awaiting_review
-
- being_reviewed
-
- awaiting_integration
-
- being_integrated
-
- completed
-
- given_test_exemption = boolean;
-
- given_regression_test_exemption = boolean;
-
- delta_number = integer;
-
- delta_uuid = string;
-
- minimum_integration = boolean;
-
- project_file_command_sync = integer;
-
- test_time = time;
-
- test_baseline_time = time;
-
- regression_test_time = time;
-
- build_time = time;
-
- architecture_times = [{ ... }];
-
- variant = string;
-
- node = string;
-
- test_time = time;
-
- test_baseline_time = time;
-
- regression_test_time = time;
-
- build_time = time;
-
- 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;
-
- history = [ { ... }, ... ];
-
- when = time;
-
- what = ( ... );
-
- who = string;
-
- why = string;
-
- 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;
-
- 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;
-
- default_test_regression_exemption = boolean;
-
- 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.
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 = [ { ... }, ... ];
-
- file_name = string;
-
- uuid = string;
-
- action = (create, modify, remove);
-
- edit_number = string;
-
- usage = (source, config, build, test, manual_test);
-
- diff_time = time;
-
- diff_file_time = time;
-
- move = string;
-
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()];
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.D001AUTHOR¶
Peter Miller | E-Mail: | millerp@canb.auug.org.au |
/\/\* | WWW: | http://www.canb.auug.org.au/~millerp/ |
Aegis | Reference Manual |