Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
aecstate(5)		      File Formats Manual		   aecstate(5)

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 direc-
	tory search times, and to avoid	various	systems' directory length lim-
	itations.

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 ex-
			isting 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 im-
			proves existing	functionality.

		internal_bug
			The change was created in response to a	bug report
			from inside the	development team.  This	repairs	exist-
			ing 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	im-
			proves 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 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 ac-
			tion 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 ae-
		cattr(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 be-
		ing_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 spe-
			cific 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 di-
		rectory.  It is	only present of	the change is in a state be-
		tween 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 be-
		ing_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 oc-
			curred.

		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 in-
			formation.  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 substitutions described in aesub(5) are avail-
			able.  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: ig-
			nored.

		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 sub-
			stitutions described by	aesub(5) are available.

			Executed as: the developer.  Current directory:	the
			development directory of the change.  Exit status: ig-
			nored.

		review_begin_notify_command = string;
			This command is	used to	notify that a review has be-
			gun.  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 sub-
			stitutions described by	aesub(5) are available.

			Executed as: the reviewer.  Current directory: the de-
			velopment directory of the change.  Exit status: ig-
			nored.

		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 sub-
			stitutions described by	aesub(5) are available.

			Executed as: the reviewer.  Current directory: the de-
			velopment directory of the change.  Exit status: ig-
			nored.

		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
			systems, such as progress and defect tracking.	All of
			the substitutions described by aesub(5)	are available.

			Executed as: the reviewer.  Current directory: the de-
			velopment directory of the change.  Exit status: ig-
			nored.

		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
			systems, such as progress and defect tracking.	De-
			faults to the same action as the develop_end_no-
			tify_command field.  All of the	substitutions de-
			scribed	by aesub(5) are	available.

			Executed as: the reviewer.  Current directory: the de-
			velopment directory of the change.  Exit status: ig-
			nored.

		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
			systems, such as progress and defect tracking.	All of
			the substitutions described by aesub(5)	are available.

			Executed as: the reviewer.  Current directory: the de-
			velopment directory of the change.  Exit status: ig-
			nored.

		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
			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 integra-
			tion 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
			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: ig-
			nored.

		default_test_exemption = boolean;
			This field contains what to do when a change is	cre-
			ated with no test exemption specified.

		default_test_regression_exemption = boolean;
			This field contains what to do when a change is	cre-
			ated with no regression	test exemption specified.

		history	= [{ ... }];
			This field contains a history of integrations for the
			project.  Updated by each successful 'aegis -Inte-
			grate_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.

			uuid = string;
				The uuid assigned to the change.

			when = time;
				This field record the time of the change inte-
				gration.

			is_a_branch = (	... )
				This field is used to remember if the com-
				pleted change was a branch.

				unknown
					It is unknown if the change is a
					branch,	this is	the default value usu-
					ally associated	with change integrated
					with an	older version of aegis.

				no
					The change is not a branch.

				yes
					The change is a	branch.

			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 com-
				plete, 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	se-
				lected 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 al-
				ways uncompress	on reading if necessary.)  De-
				faults to false	if not set.

				Unless you have	an exceptionally large
				project, coupled with fast CPUs	and high net-
				work 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 en-
				ters 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 re-
					view 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 be-
				ing 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 re-
			names.	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_devel-
			oped 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 delet-
			ing 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 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
	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 ac-
	cess the the relevant file state (see aefstate(5) for more informa-
	tion).

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.25.D510
	Copyright (C) 1991, 1992, 1993,	1994, 1995, 1996, 1997,	1998, 1999,
	2000, 2001, 2002, 2003,	2004, 2005, 2006, 2007,	2008, 2009, 2010,
	2011, 2012 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:	 pmiller@opensource.org.au
	/\/\*		  WWW:	 http://miller.emu.id.au/pmiller/

Reference Manual		     Aegis			   aecstate(5)

NAME | SYNOPSIS | DESCRIPTION | CONTENTS | WRITING REPORT SCRIPTS | SEE ALSO | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=aecstate&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help