aecstate(5) aecstate(5) NNAAMMEE aecstate - aegis change state file SSYYNNOOPPSSIISS _p_r_o_j_e_c_t/info/change/_[_0_-_9_]/_[_0_-_9_]_[_0_-_9_]_[_0_-_9_] DDEESSCCRRIIPPTTIIOONN 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. CCOONNTTEENNTTSS 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 chnage 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. 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 _d_e_v_e_l_o_p _e_n_d _a_c_t_i_o_n project attribute.) being_reviewed The change has been developed, and is being reviewed. (Optional, controlled by the _d_e_v_e_l_o_p _e_n_d _a_c_t_i_o_n 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. delta_number = integer; This field records the delta number for this change. It is only present if the change is in one of the _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d or _c_o_m_p_l_e_t_e_d states. 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 _a_e_g_i_s _-_T_e_s_t command was run for all architectures. It is only present in the _b_e_i_n_g___d_e_v_e_l_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d states. test_baseline_time = time; This field records the time the last successful _a_e_g_i_s _-_T_e_s_t _-_B_a_s_e_L_i_n_e command was run for all architectures. It is only present in the _b_e_i_n_g___d_e_v_e_l_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d states. regression_test_time = time; This field records the time the last successful _a_e_g_i_s _-_T_e_s_t _-_R_E_G_r_e_s_s_i_o_n command was run for all architectures. It is only present in the _b_e_i_n_g___d_e_v_e_l_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d states. build_time = time; This field records the last time the last successful _a_e_g_i_s _-_B_u_i_l_d command was run for all architectures. It is only present in the _b_e_i_n_g___d_e_v_e_l_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d states. architecture_times = [{ ... }]; This field records the time of various operations for each variant named in the _a_r_c_h_i_t_e_c_t_u_r_e field. It is only present in the _b_e_i_n_g___d_e_v_e_l_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d states. variant = string; This field is one of the patterns named in the _a_r_c_h_i_t_e_c_t_u_r_e 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 _a_e_g_i_s _-_T_e_s_t command was run for this specific pattern instance. test_baseline_time = time; This field records the last time the last successful _a_e_g_i_s _-_T_e_s_t _-_B_a_s_e_L_i_n_e command was run for this specific pattern instance. regression_test_time = time; This field records the last time the last successful _a_e_g_i_s _-_T_e_s_t _-_R_E_G_r_e_s_s_i_o_n command was run for this specific pattern instance. build_time = time; This field records the last time the last successful _a_e_g_i_s _-_B_u_i_l_d command was run for this specific pattern instance. development_directory = string; This field is the absolute path of the change's development directory. It is only present of the change is in a state between _b_e_i_n_g___d_e_v_e_l_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d inclusive. 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 _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d 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 _r_e_v_i_e_w___f_a_i_l and _i_n_t_e_g_r_a_t_e___f_a_i_l, this field will contain why the change failed. branch = { ... }; This field is only present for branches (long transactions). umask = integer; File permission mode mask. See _u_m_a_s_k(2) for more information. This value will always be OR'ed with 022, because _a_e_g_i_s 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 _d_e_v_e_l_o_p___e_n_d___a_c_t_i_o_n field may not contradict the _d_e_v_e_l_o_p_e_r___m_a_y___r_e_v_i_e_w field. If developers may not review their own work, then their changes may not goto directly to the _b_e_i_n_g _i_n_t_e_g_r_a_t_e_d 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 _a_e_d_b _-_U_s_e_r command to force development of a change by a specific user. All of the substitutions described in _a_e_s_u_b(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 _a_e_s_u_b(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 _a_e_s_u_b(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 _a_e_s_u_b(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 _a_e_s_u_b(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 _a_e_s_u_b(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 _d_e_v_e_l_o_p___e_n_d___n_o_t_i_f_y___c_o_m_m_a_n_d field. All of the substitutions described by _a_e_s_u_b(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 _a_e_s_u_b(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 _a_e_s_u_b(5) are available. 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 _a_e_s_u_b(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. 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 _a_e_n_c_(_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 _a_e_n_c(1) change numbers ``fill in'' any gaps. Defaults to true if not set. minimum_branch_number = integer; The minimum branch number for _a_e_n_b_r_(_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 _a_e_d_e(1) action. _g_o_t_o___b_e_i_n_g___r_e_v_i_e_w_e_d This means that the change goes from the _b_e_i_n_g___d_e_v_e_l_o_p_e_d state to the _b_e_i_n_g___r_e_v_i_e_w_e_d state. The _a_e_r_b(1) command only sends informative email. _g_o_t_o___a_w_a_i_t_i_n_g___r_e_v_i_e_w This means that the change goes from the _b_e_i_n_g___d_e_v_e_l_o_p_e_d state to the _a_w_a_i_t_i_n_g___r_e_v_i_e_w state. The _a_e_r_b(1) command is now mandatory. _g_o_t_o___a_w_a_i_t_i_n_g___i_n_t_e_g_r_a_t_i_o_n This means that the change goes from the _b_e_i_n_g___d_e_v_e_l_o_p_e_d state into the _a_w_a_i_t_i_n_g___i_n_m_t_e_g_a_r_t_i_o_n state. Code review is skipped entirely. Note that the _d_e_v_e_l_o_p___e_n_d___a_c_t_i_o_n field may not contradict the _d_e_v_e_l_o_p_e_r___m_a_y___r_e_v_i_e_w field. If developers may not review their own work, then their changes may not goto directly to the _b_e_i_n_g _i_n_t_e_g_r_a_t_e_d state (as this means much the same thing). A contradictory setting will be replaced with _g_o_t_o___b_e_i_n_g___r_e_v_i_e_w_e_d. OObbssoolleettee FFiieellddss 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 _a_e_f_s_t_a_t_e(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. 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 _a_e_g_i_s _-_D_I_F_F_e_r_e_n_c_e command). This field is not present for new files. usage = (source, 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 _a_e_g_i_s _-_D_I_F_F_e_r_e_n_c_e command was run. It is only present between the _b_e_i_n_g___d_e_v_e_l_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d 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 _a_e_g_i_s _-_D_I_F_F_e_r_e_n_c_e command was run. It is only present between the _b_e_i_n_g___d_e_v_e_l_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d 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. WWRRIITTIINNGG RREEPPOORRTT SSCCRRIIPPTTSS 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 _b_r_a_n_c_h_._c_h_a_n_g_e field, you are given access to the change state data of that change on the branch. When you index the _s_r_c field by a filename string, you may obtain access the the relevant file state (see _a_e_f_s_t_a_t_e(5) for more information). SSEEEE AALLSSOO _a_e_n_c(1) create a new change _a_e_g_i_s(5) aegis file format syntax _a_e_c_a_t_t_r(5) change attributes file format _a_e_f_s_t_a_t_e(5) file state file format CCOOPPYYRRIIGGHHTT aegis version .C001 Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Peter Miller; All rights reserved. The aegis program comes with ABSOLUTELY NO WARRANTY; for details use the '_a_e_g_i_s _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the '_a_e_g_i_s _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command. AAUUTTHHOORR Peter Miller E-Mail: millerp@canb.auug.org.au /\/\* WWW: http://www.canb.auug.org.au/~millerp/ Reference Manual Aegis 1