plans/1.0/bugzilla-milestone-plans.xml - www.eclipse.org/webtools - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <?xml-stylesheet type="text/xsl" href="stylesheets/wtp.xsl"?>

 <html>
 	<head>
 		<title>The Mapping Between Bugzilla and Milestone Plans</title>
 		<meta content="www" name="root" />
 	</head>
 	<body>
 		<h1>bugzilla and milestone plans</h1>
 		<address><a href="http://eclipse.org/webtools/people/ryman.html">Arthur Ryman</a></address>
 		<address>2005-10-13</address>
 		<br />
 		<h2>Introduction</h2>
 		<p>
 			Like all Eclipse projects, WTP uses Bugzilla as the
 			definitive source of information about defects and
 			enhancements, collectively referred to as
 			<em>bugs</em>
 			. However, Bugzilla is not well-suited to storing detailed
 			design information or work plans. The WTP development
 			process therefore provides
 			<em>milestone plan</em>
 			documents for capturing additional information. Clearly, the
 			milestone plans must be consistent with Bugzilla. This
 			document describes the structure of milestone plans and how
 			they map to Bugzilla.
 		</p>
 		<h3>
 			<a href="#Milestone-Plans">Milestone Plans</a>
 		</h3>
 		<h3>
 			<a href="#Bugzilla">Bugzilla</a>
 		</h3>
 		<h3>
 			<a href="#Status">Status</a>
 		</h3>
 		<br />
 		<h2>
 			<a name="Milestone-Plans">Milestone Plans</a>
 		</h2>
 		<p>
 			WTP milestones plans a highly structure XML documents that
 			capture additional information about work items. The formal
 			structure of milestones plans is described by the following
 			XML schema:
 		</p>
 		<h3>
 			<a href="milestonePlan.xsd">milestonePlan.xsd</a>
 		</h3>
 		<p>
 			In general, a milestone plan document may contain
 			information about work items for several components and
 			milestones. However, for WTP 1.0, we have adopted the
 			restriction that each document contains information for
 			exactly one milestone of one component. Furthermore, these
 			plans are given the standard filename,
 			<code>milestone_plan.xml</code>
 			, and are placed in a directory that corresponds to the
 			subproject, component, and milestone. For example, the
 			milestone plan for M8 of the server component of the wst
 			subproject is placed in the file
 			<code>
 				/webtools/plans/1.0/wst/server/M8/milestone_plan.xml
 			</code>
 			.
 		</p>
 		<p>
 			The following table describes some of the main elements and
 			attributes of a milestone plan document:
 		</p>
 		<table cellspacing="8">

 			<tr>
 				<th align="right">Work Item Data</th>
 				<th align="left">Description</th>
 			</tr>
 			<tr>
 				<th align="right">/plan/component/@subproject</th>
 				<td>
 					The name of the subproject of the component, e.g.
 					wst or jst.
 				</td>
 			</tr>

 			<tr>
 				<th align="right">/plan/component/@name</th>
 				<td>The name of the component, e.g. server or html.</td>
 			</tr>

 			<tr>
 				<th align="right">/plan/component/milestone/@name</th>
 				<td>The name of the milestone, e.g. M8 or M9.</td>
 			</tr>

 			<tr>
 				<th align="right">
 					/plan/component/milestone/category/@name
 				</th>
 				<td>
 					The name of the work item category, e.g. API or
 					Performance.
 				</td>
 			</tr>

 			<tr>
 				<th align="right">
 					/plan/component/milestone/category/item/description
 				</th>
 				<td>The short description of the work item.</td>
 			</tr>
 			<tr>
 				<th align="right">
 					/plan/component/milestone/category/item/@bug
 				</th>
 				<td>
 					The bug number associated with the work item. This
 					is optional. However, it is good practice to have a
 					bug for each work item. Several work items may be
 					associated with the same bug.
 				</td>
 			</tr>

 			<tr>
 				<th align="right">
 					/plan/component/milestone/category/item/@priority
 				</th>
 				<td>
 					The importance of the work item, e.g. high, medium,
 					or low. High priority work items are those that
 					define the milestone. A milestone is not considered
 					complete if any high priority work items are
 					incomplete.
 				</td>
 			</tr>

 			<tr>
 				<th align="right">
 					/plan/component/milestone/category/item/@status
 				</th>
 				<td>
 					The status of the work item, e.g. new, investigate,
 					in-progress, done, deferred, time-permitted.
 				</td>
 			</tr>

 			<tr>
 				<th align="right">
 					/plan/component/milestone/category/item/@helpWanted
 				</th>
 				<td>
 					Indicates if help is wanted for this work item, e.g.
 					true or false.
 				</td>
 			</tr>

 			<tr>
 				<th align="right">
 					/plan/component/milestone/category/item/developer/@name
 				</th>
 				<td>
 					The name of the developer assigned to the work item.
 					In general, an item may have zero or more developers
 					assigned to it. The developer name may be any string
 					value, however, it should be the Bugzilla login name
 					of the developer which is their email address.
 				</td>
 			</tr>

 		</table>

 		<h2>
 			<a name="Bugzilla">Bugzilla</a>
 		</h2>

 		<p>
 			It should be clear from the above description that there is
 			a lot of similarity between milestone plan work items and
 			bugs. Every work item should be associated with a bug since
 			one of the WTP development practices is to include a bug
 			number in any CVS commit. The main reason for defining a
 			work item it to plan some change to WTP and so a bug number
 			will be eventually needed for the work. However, we allow
 			for the possibility that some bugs may involve several work
 			items.
 		</p>

 		<p>
 			When a work item has been associated with a bug, we need to
 			ensure that the information in Bugzilla is consistent with
 			the work item. The following table describes the mapping
 			from Buzilla fields to work item elements and attributes:
 		</p>

 		<table cellspacing="8">
 			<tr>
 				<th align="right">Bugzilla&#160;Field</th>
 				<th align="left">Work&#160;Item&#160;Data</th>
 			</tr>
 			<tr>
 				<th align="right" valign="top">Bug#:</th>
 				<td>
 					This maps to the bug number associated with the work
 					item and is the basis for comparing a work item to a
 					bug.
 				</td>
 			</tr>

 			<tr>
 				<th align="right" valign="top">
 					<a
 						href="https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Web%20Tools">
 						Component:
 					</a>
 				</th>
 				<td>
 					Bugzilla components generally map to WTP components.
 					The Bugzilla component name is usually a combination
 					of the subproject and component name, e.g. the
 					Bugzilla component
 					<code>wst.server</code>
 					maps to the
 					<code>server</code>
 					component of the
 					<code>wst</code>
 					subproject.
 					<strong>
 						It is therefore an error if the subproject and
 						component of the work item does not match the
 						Bugzilla component.
 					</strong>
 					There are some additional components in Bugzilla
 					that do not match WTP components. For example, there
 					are Bugzilla components for the wst and jst
 					subprojects. To cover this case, we introduce the
 					pseudo-component named
 					<code>subproject</code>
 					to indicate that the scope of the Bugzilla component
 					is the entire subproject. There are also some
 					Bugzilla components, such as
 					<code>documentation</code>
 					and
 					<code>website</code>
 					, whose scope spans subprojects. For this case we
 					introduce the pseudo-subproject names
 					<code>wtp</code>
 					.
 				</td>
 			</tr>

 			<tr>
 				<th align="right" valign="top">
 					Target&#160;Milestone:
 				</th>
 				<td>
 					The Bugzilla target milestone maps directly to the
 					work item milestone except that the name used in
 					Bugzilla includes the release number, e.g. milestone
 					M8 of WTP 1.0 matches the Bugzilla target milestone
 					of
 					<code>1.0 M8</code>
 					.
 					<strong>
 						It is an error if the work item milestone
 						doesn't match the Bugzilla target milestone.
 					</strong>
 				</td>
 			</tr>

 			<tr>
 				<th align="right" valign="top">
 					<a
 						href="https://bugs.eclipse.org/bugs/page.cgi?id=fields.html#priority">
 						Priority:
 					</a>
 				</th>
 				<td>
 					The Bugzilla priority maps to the work item
 					priority. However, a translation must be made since
 					the Bugzilla priorities have the values P1, P2, P3,
 					P4, and P5, whereas the work item priorities have
 					the values high, medium, and low. I suggest that we
 					either adopt the Bugzilla priorities in the
 					milestone plans or we use the following mappings: P1
 					is high, P2 and P3 are medium, and P4 and P5 are
 					low.
 				</td>
 			</tr>

 			<tr>
 				<th align="right" valign="top">
 					<a
 						href="https://bugs.eclipse.org/bugs/page.cgi?id=fields.html#status">
 						Status:
 					</a>
 				</th>
 				<td>
 					The Bugzilla status maps roughly to the work item
 					status. The Bugzilla status has the values
 					UNCONFIRMED NEW, ASSIGNED, REOPENED, RESOLVED, and
 					VERIFIED, CLOSED whereas the work item status has
 					the values in-progress, done, deferred,
 					time-permitted, new, and investigate. We could
 					either adopt the Bugzilla status values in the
 					milestone plans, or use the following partial
 					mapping: if in-progress, then ASSIGNED, if done then
 					CLOSED, if new then NEW, and if investigate the
 					UNCONFIRMED.
 				</td>
 			</tr>

 			<tr>
 				<th align="right" valign="top">
 					<a
 						href="https://bugs.eclipse.org/bugs/page.cgi?id=fields.html#assigned_to">
 						Assigned&#160;To:
 					</a>
 				</th>
 				<td>
 					The Bugzilla assigned to field maps roughly to the
 					work item developer. However, a work item may have
 					zero or more developers and a bug may be associated
 					with zero or more work items. Therefore a bug could
 					have many developers associated with it via the
 					milestone plans. This seems to be a mismatch in
 					granularity since in a sense we are treating work
 					items as more granular than bugs since many work
 					items may be associated with one bug, yet each bug
 					is assigned to a single developer. One way out may
 					be to add an attribute to the developer element to
 					indicate that they have overall responsibility for
 					the bug. Alternatively, we could simply not enforce
 					any mapping here.
 				</td>
 			</tr>

 			<tr>
 				<th align="right" valign="top">
 					<a
 						href="https://bugs.eclipse.org/bugs/describekeywords.cgi">
 						Keywords:
 					</a>
 				</th>
 				<td>
 					Bugzilla keywords are used for several purposes. The
 					keyword helpwanted clearly maps the the work item
 					helpWanted indicator. We could impose the rule that
 					a work item has a helpWanted indicator set if and
 					only if the bug has the keyword helpwanted. The
 					other keywords include values that map to several
 					common work item categories, e.g. accessibility,
 					api, performance, and usability. Since the list of
 					allowed keywords is fixed we could adopt the rule
 					that the allowed work item categories must be
 					allowed keywords. Each work item could include one
 					or more allowed keywords for its category. The union
 					of the keywords of all the work items that are
 					associated with a bug should be set on the bug.
 				</td>
 			</tr>

 		</table>

 		<p>
 			Another alternative to keeping the work items consistent
 			with their associated bugs is to make all redundant data
 			items optional, in which case their values are obtained from
 			the bug.
 		</p>

 		<h2>
 			<a name="Status" />
 			Status
 		</h2>

 		<p>
 			At present,
 			<a href="buglist-report-index.html">bug list reports</a>
 			are generated as part of the Web site build script. However,
 			since they are generated from data extracted from Bugzilla,
 			they become stale as soon as Bugzilla is updated. The ideal
 			solution is to make the bug list reports dynamic. We are
 			evaluating two approaches. The simplest is to use PHP,
 			however, this requires that the PHP XSLT extension be
 			enabled.
 			<a
 				href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=112149">
 				Bug 112149
 			</a>
 			has been opened to request this enhancement. The other
 			solution is to use a Java Web application based on either
 			Xalan or Cocoon to do the transformation.
 		</p>


 	</body>
 </html>
	<?xml version="1.0" encoding="UTF-8"?>
	<?xml-stylesheet type="text/xsl" href="stylesheets/wtp.xsl"?>

	<html>
	<head>
	<title>The Mapping Between Bugzilla and Milestone Plans</title>
	<meta content="www" name="root" />
	</head>
	<body>
	<h1>bugzilla and milestone plans</h1>
	<address><a href="http://eclipse.org/webtools/people/ryman.html">Arthur Ryman</a></address>
	<address>2005-10-13</address>
	<br />
	<h2>Introduction</h2>
	<p>
	Like all Eclipse projects, WTP uses Bugzilla as the
	definitive source of information about defects and
	enhancements, collectively referred to as
	<em>bugs</em>
	. However, Bugzilla is not well-suited to storing detailed
	design information or work plans. The WTP development
	process therefore provides
	<em>milestone plan</em>
	documents for capturing additional information. Clearly, the
	milestone plans must be consistent with Bugzilla. This
	document describes the structure of milestone plans and how
	they map to Bugzilla.
	</p>
	<h3>
	<a href="#Milestone-Plans">Milestone Plans</a>
	</h3>
	<h3>
	<a href="#Bugzilla">Bugzilla</a>
	</h3>
	<h3>
	<a href="#Status">Status</a>
	</h3>
	<br />
	<h2>
	<a name="Milestone-Plans">Milestone Plans</a>
	</h2>
	<p>
	WTP milestones plans a highly structure XML documents that
	capture additional information about work items. The formal
	structure of milestones plans is described by the following
	XML schema:
	</p>
	<h3>
	<a href="milestonePlan.xsd">milestonePlan.xsd</a>
	</h3>
	<p>
	In general, a milestone plan document may contain
	information about work items for several components and
	milestones. However, for WTP 1.0, we have adopted the
	restriction that each document contains information for
	exactly one milestone of one component. Furthermore, these
	plans are given the standard filename,
	<code>milestone_plan.xml</code>
	, and are placed in a directory that corresponds to the
	subproject, component, and milestone. For example, the
	milestone plan for M8 of the server component of the wst
	subproject is placed in the file
	<code>
	/webtools/plans/1.0/wst/server/M8/milestone_plan.xml
	</code>
	.
	</p>
	<p>
	The following table describes some of the main elements and
	attributes of a milestone plan document:
	</p>
	<table cellspacing="8">

	<tr>
	<th align="right">Work Item Data</th>
	<th align="left">Description</th>
	</tr>
	<tr>
	<th align="right">/plan/component/@subproject</th>
	<td>
	The name of the subproject of the component, e.g.
	wst or jst.
	</td>
	</tr>

	<tr>
	<th align="right">/plan/component/@name</th>
	<td>The name of the component, e.g. server or html.</td>
	</tr>

	<tr>
	<th align="right">/plan/component/milestone/@name</th>
	<td>The name of the milestone, e.g. M8 or M9.</td>
	</tr>

	<tr>
	<th align="right">
	/plan/component/milestone/category/@name
	</th>
	<td>
	The name of the work item category, e.g. API or
	Performance.
	</td>
	</tr>

	<tr>
	<th align="right">
	/plan/component/milestone/category/item/description
	</th>
	<td>The short description of the work item.</td>
	</tr>
	<tr>
	<th align="right">
	/plan/component/milestone/category/item/@bug
	</th>
	<td>
	The bug number associated with the work item. This
	is optional. However, it is good practice to have a
	bug for each work item. Several work items may be
	associated with the same bug.
	</td>
	</tr>

	<tr>
	<th align="right">
	/plan/component/milestone/category/item/@priority
	</th>
	<td>
	The importance of the work item, e.g. high, medium,
	or low. High priority work items are those that
	define the milestone. A milestone is not considered
	complete if any high priority work items are
	incomplete.
	</td>
	</tr>

	<tr>
	<th align="right">
	/plan/component/milestone/category/item/@status
	</th>
	<td>
	The status of the work item, e.g. new, investigate,
	in-progress, done, deferred, time-permitted.
	</td>
	</tr>

	<tr>
	<th align="right">
	/plan/component/milestone/category/item/@helpWanted
	</th>
	<td>
	Indicates if help is wanted for this work item, e.g.
	true or false.
	</td>
	</tr>

	<tr>
	<th align="right">
	/plan/component/milestone/category/item/developer/@name
	</th>
	<td>
	The name of the developer assigned to the work item.
	In general, an item may have zero or more developers
	assigned to it. The developer name may be any string
	value, however, it should be the Bugzilla login name
	of the developer which is their email address.
	</td>
	</tr>

	</table>

	<h2>
	<a name="Bugzilla">Bugzilla</a>
	</h2>

	<p>
	It should be clear from the above description that there is
	a lot of similarity between milestone plan work items and
	bugs. Every work item should be associated with a bug since
	one of the WTP development practices is to include a bug
	number in any CVS commit. The main reason for defining a
	work item it to plan some change to WTP and so a bug number
	will be eventually needed for the work. However, we allow
	for the possibility that some bugs may involve several work
	items.
	</p>

	<p>
	When a work item has been associated with a bug, we need to
	ensure that the information in Bugzilla is consistent with
	the work item. The following table describes the mapping
	from Buzilla fields to work item elements and attributes:
	</p>

	<table cellspacing="8">
	<tr>
	<th align="right">Bugzilla Field</th>
	<th align="left">Work Item Data</th>
	</tr>
	<tr>
	<th align="right" valign="top">Bug#:</th>
	<td>
	This maps to the bug number associated with the work
	item and is the basis for comparing a work item to a
	bug.
	</td>
	</tr>

	<tr>
	<th align="right" valign="top">
	<a
	href="https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Web%20Tools">
	Component:
	</a>
	</th>
	<td>
	Bugzilla components generally map to WTP components.
	The Bugzilla component name is usually a combination
	of the subproject and component name, e.g. the
	Bugzilla component
	<code>wst.server</code>
	maps to the
	<code>server</code>
	component of the
	<code>wst</code>
	subproject.
	<strong>
	It is therefore an error if the subproject and
	component of the work item does not match the
	Bugzilla component.
	</strong>
	There are some additional components in Bugzilla
	that do not match WTP components. For example, there
	are Bugzilla components for the wst and jst
	subprojects. To cover this case, we introduce the
	pseudo-component named
	<code>subproject</code>
	to indicate that the scope of the Bugzilla component
	is the entire subproject. There are also some
	Bugzilla components, such as
	<code>documentation</code>
	and
	<code>website</code>
	, whose scope spans subprojects. For this case we
	introduce the pseudo-subproject names
	<code>wtp</code>
	.
	</td>
	</tr>

	<tr>
	<th align="right" valign="top">
	Target Milestone:
	</th>
	<td>
	The Bugzilla target milestone maps directly to the
	work item milestone except that the name used in
	Bugzilla includes the release number, e.g. milestone
	M8 of WTP 1.0 matches the Bugzilla target milestone
	of
	<code>1.0 M8</code>
	.
	<strong>
	It is an error if the work item milestone
	doesn't match the Bugzilla target milestone.
	</strong>
	</td>
	</tr>

	<tr>
	<th align="right" valign="top">
	<a
	href="https://bugs.eclipse.org/bugs/page.cgi?id=fields.html#priority">
	Priority:
	</a>
	</th>
	<td>
	The Bugzilla priority maps to the work item
	priority. However, a translation must be made since
	the Bugzilla priorities have the values P1, P2, P3,
	P4, and P5, whereas the work item priorities have
	the values high, medium, and low. I suggest that we
	either adopt the Bugzilla priorities in the
	milestone plans or we use the following mappings: P1
	is high, P2 and P3 are medium, and P4 and P5 are
	low.
	</td>
	</tr>

	<tr>
	<th align="right" valign="top">
	<a
	href="https://bugs.eclipse.org/bugs/page.cgi?id=fields.html#status">
	Status:
	</a>
	</th>
	<td>
	The Bugzilla status maps roughly to the work item
	status. The Bugzilla status has the values
	UNCONFIRMED NEW, ASSIGNED, REOPENED, RESOLVED, and
	VERIFIED, CLOSED whereas the work item status has
	the values in-progress, done, deferred,
	time-permitted, new, and investigate. We could
	either adopt the Bugzilla status values in the
	milestone plans, or use the following partial
	mapping: if in-progress, then ASSIGNED, if done then
	CLOSED, if new then NEW, and if investigate the
	UNCONFIRMED.
	</td>
	</tr>

	<tr>
	<th align="right" valign="top">
	<a
	href="https://bugs.eclipse.org/bugs/page.cgi?id=fields.html#assigned_to">
	Assigned To:
	</a>
	</th>
	<td>
	The Bugzilla assigned to field maps roughly to the
	work item developer. However, a work item may have
	zero or more developers and a bug may be associated
	with zero or more work items. Therefore a bug could
	have many developers associated with it via the
	milestone plans. This seems to be a mismatch in
	granularity since in a sense we are treating work
	items as more granular than bugs since many work
	items may be associated with one bug, yet each bug
	is assigned to a single developer. One way out may
	be to add an attribute to the developer element to
	indicate that they have overall responsibility for
	the bug. Alternatively, we could simply not enforce
	any mapping here.
	</td>
	</tr>

	<tr>
	<th align="right" valign="top">
	<a
	href="https://bugs.eclipse.org/bugs/describekeywords.cgi">
	Keywords:
	</a>
	</th>
	<td>
	Bugzilla keywords are used for several purposes. The
	keyword helpwanted clearly maps the the work item
	helpWanted indicator. We could impose the rule that
	a work item has a helpWanted indicator set if and
	only if the bug has the keyword helpwanted. The
	other keywords include values that map to several
	common work item categories, e.g. accessibility,
	api, performance, and usability. Since the list of
	allowed keywords is fixed we could adopt the rule
	that the allowed work item categories must be
	allowed keywords. Each work item could include one
	or more allowed keywords for its category. The union
	of the keywords of all the work items that are
	associated with a bug should be set on the bug.
	</td>
	</tr>

	</table>

	<p>
	Another alternative to keeping the work items consistent
	with their associated bugs is to make all redundant data
	items optional, in which case their values are obtained from
	the bug.
	</p>

	<h2>
	<a name="Status" />
	Status
	</h2>

	<p>
	At present,
	<a href="buglist-report-index.html">bug list reports</a>
	are generated as part of the Web site build script. However,
	since they are generated from data extracted from Bugzilla,
	they become stale as soon as Bugzilla is updated. The ideal
	solution is to make the bug list reports dynamic. We are
	evaluating two approaches. The simplest is to use PHP,
	however, this requires that the PHP XSLT extension be
	enabled.
	<a
	href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=112149">
	Bug 112149
	</a>
	has been opened to request this enhancement. The other
	solution is to use a Java Web application based on either
	Xalan or Cocoon to do the transformation.
	</p>


	</body>
	</html>