development/WTPDevelopmentPractice.html - www.eclipse.org/webtools - Git at Google

 <!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
 <meta name="GENERATOR" content="IBM Software Development Platform" />
 <link rel="stylesheet" href="http://www.eclipse.org/default_style.css"
 	type="text/css" />
 <title>WTP Development Practices</title>
 <!-- David Williams, 10/25/04 (david_williams@us.ibm.com) -->
 </head>

 <body alink="#ff0000" bgcolor="#ffffff" link="#0000ee" text="#000000"
 	vlink="#551a8b">

 <table border="0" cellpadding="2" cellspacing="5" width="100%">

 	<tbody>
 		<tr>

 			<td width="60%">
 			<p align="LEFT"><FONT size="6"><B><FONT
 				face="Verdana, Arial, Helvetica, sans-serif">WTP Development
 			Practices</FONT></B></FONT><FONT size="1"><FONT
 				face="Arial, Helvetica, sans-serif"><FONT color="#8080ff"><br />
 			WTP Development Practices</FONT></FONT></FONT></p>
 			</td>


 			<td></td>

 			<td rowspan="2" width="19%"><img
 				src="http://www.eclipse.org/images/Idea.jpg" border="0" height="86"
 				width="120" alt="" /></td>

 		</tr>


 	</tbody>
 </table>
 <p>This document is to describe some guidelines, procedures, and
 &quot;best practices&quot; for doing WTP development. In some cases its
 simply covers consistency/procedure issues, but also recommends best
 practices to help community review and involvement. While all component
 teams can have their own practices, if anyone has some good tips or
 recommendations, please post to wtp-dev for discussion or suggest that
 they be added here.</p>
 <h2>Code into CVS</h2>

 <p>The component developers should provide the following information to
 accompany code checked into CVS. Some of this information will become
 part of the components 'development' directory in cvs, or on the
 component's WTP website, and should be kept up to date as changes take
 place and development progresses. (See <A
 	href="#webanddevelopmentresources" target="_self">Web and development
 resources</A> for guidelines on what goes where).</p>

 <ul>
 	<li>
 	<p>A brief description of the component. This might be an initial
 	design document, if it exists, but the actual design document can come
 	later. This brief description should overview the function provided by
 	the component, but should also list at least a few API's, extension
 	points, or other &quot;starting points&quot; for anyone wanting to use
 	or extend the component. (See <A href="../wst/components/sse/archiveOfOldish/PluginOverview.html">PluginOverview.html</A>
 	for example).</p>
 	</li>

 	<li>
 	<p>A brief initial work plan: describing what development tasks are
 	expected for the next milestone or two (or simply in &quot;future&quot;
 	if not yet planned for a specific milestone). Specific bugs and feature
 	requests can be tracked with bugzilla, but this plan should be given as
 	a prose &quot;overview&quot; or highlights of work that is planned
 	towards refactoring or making the component &quot;platform
 	quality&quot;. (See <A href="../wst/components/sse/archiveOfOldish/SSEDevelopmentPlan.html">SSEDevelopmentPlan.html</A>
 	for example). In particular, if there are areas that can be explicity
 	tagged with &quot;HELP WANTED&quot;, that would be good since can help
 	let potenital contributors know what areas</p>
 	</li>

 	<li>
 	<p>Each plugin and build feature should contain a 'description' in the
 	plugin.xml (or feature.xml) file (there is a description tag for such
 	purpose).</p>
 	</li>

 	<li>
 	<p>A plan for how the component will be documented: both the
 	&quot;developers guide&quot; type of information (see Platform Plugin
 	Developers Guide and JDT Plugin Developers Guide in the base Eclipse
 	for examples) and also the status and plan for design overviews and
 	&quot;javadoc&quot; type of information.</p>
 	</li>

 	<li>
 	<p>All copyrights and appropriate license files should be correctly
 	provided.</p>
 	</li>
 	<LI><b>CVS Hygiene</b></LI>
 	<ul>
 		<li>
 		<p><B>Team Project Set.</B> Each component team should have a
 		&quot;team project set&quot; in their 'development' directory to make
 		it easy for others to check out what is needed for that particular
 		component.</p>
 		</li>

 		<li>
 		<p><B>Source Folders</B> A minor consistency point: If there's only
 		one &quot;source directory&quot; it should be named 'src'. If there's
 		more than one, the additional ones should be named similar to
 		src-wizards, so its obvious both that's its source, and what its
 		conceptual division is. Multiple folders are not typically required,
 		but can be handy when one team has responsibility for one part, and
 		another team responsibility for another part of the plugin.</p>
 		</li>

 		<LI>
 		<P><B>Compiled code jar.</B> Its recommended the jar for the plugin be
 		in the "root" of the plugin. Its also recommended a directory such as
 		"runtime" be reserved for those few cases where a pre-existing binary
 		jar is shipped with a plugin.</P>
 		</LI>

 		<li>
 		<p><B>cvsignore</B> A .cvsignore file should be provided which has at
 		least 'bin' in it to prevent the check in of .class files -- please do
 		this before bin is committed to the repository (since you can not
 		ignore after its there). Typically, other &quot;transient files&quot;
 		(such as a non-custom build.xml, etc) are also added to this
 		.cvsignore file.</p>
 		</li>

 		<li>
 		<p><B>Source Formatting</B> Source should be formatted according to
 		some stated standard (e.g. see /wtp-jst-home/development/format) and
 		appropriate Eclipse compiler options used (e.g. see
 		/wtp-jst-home/development/compilersettings) to produce &quot;clean
 		code&quot; (no unnecessary casts, no unused imports, etc.) Its also
 		recommended the source originally have 'sorted members'. The intent
 		here is to have clean, consistent code that makes it easier for others
 		to do diffs, compares, and supply patches.</p>
 		</li>
 		<LI>
 		<P><B>Obsolete directories in CVS. </B> If, due to renaming,
 		refactoring, or just spelling mistakes, a directory in CVS should
 		literally be deleted, to avoid a large of confusing directories,
 		please use following procedure. First, if it contains source, its
 		recommend to version that plugin's source, with a name such as
 		&quot;obsolete&lt;date&gt;&quot;. Next delete the source, and leave in
 		its place a single file named &quot;obsolete.txt&quot; . If
 		appropriate, that file can contain information about why obsolete,
 		where the replacement is, etc. Lastly, someone will occasionally delete those directories from CVS (not
 		typically an desirable thing to do, since it is a source code control
 		system! Note: if some code or project simply become old or outdated, it is usually not appropriate to delete it since it might be required for simple historical reason. In these cases, its recommed to version the final version with some descriptive name like &quot;outdated&lt;date&gt;&quot; and leave a file in the directory called something like &quot;outdated.txt&quot; with some description of when and why, if there's a similar function offered elsewhere, etc. </P>
 		</LI>
 	</ul>
 </ul>
 <H3>Modified Code into CVS</H3>
 <P>As features are added to bugzilla and fixes done and patches are
 applied, enter the <B>CVS commit comment</B> as<BR>
 <CODE>[BUGNO] Bugzilla abstract or explanation (eg: [6788] Fixed NPE on
 open) </CODE><BR>
 This will allow us to generate a &quot;what is fixed &quot; list
 automatically with links to bugzilla with each build. For an example of
 output in another project, see <BR>
 <A
 	href="http://download.eclipse.org/tools/emf/scripts/news-release-notes.php?ver=2.1.0#I200411180800">http://download.eclipse.org/tools/emf/scripts/news-release-notes.php?ver=2.1.0#I200411180800</A><BR>
 </P>
 <H2>Plugin Design Conventions</H2>
 <P><B>Avoid using the export=&quot;true&quot; attribute on pre-req
 (imported) plugins</B>.
 </P>
 <P>Its never appropriate to use it just so your upstream clients save
 typing a line in their plugin.xml file. But, sometimes it is appropriate
 to use it -- when the classes/interfaces in pre-req plugin really are
 part of the pre-reqing plugins API. If it fits this later case,
 that is it is part of the plugin's API, please document what part of the API requires it. For example: <BR>
 <CODE> &lt;!-- need to re-export org.eclipse.text since our API depends
 on it, <BR>
 such as IStructuredDocument extends IDocument <BR>
 --&gt; <BR>
 &lt;import plugin=&quot;org.eclipse.text&quot;
 export=&quot;true&quot;/&gt; </CODE><BR>The reason for this convention is that it forces upstream clients to stay better aware of exactly what they are pre-reqing instead of picking up some classes simply as a side effect of pre-reqing your plugin.  </P>
 <h2><A name="webanddevelopmentresources">Web and development resources</A></h2>
 <P>By convention, a directory named 'development' should be used in the
 component's CVS directory structure. This directory would be a peer with
 'features' and 'plugins'. These directories should hold things that may
 be useful or relevant not only to the developers of the components, but
 others interested in contributing (e.g. project team sets, Rose source
 files of designs, etc). Things in these directories are not intended to
 be in a build. If they are intended for an SDK build, they would be part
 of the plugins directory structure.</P>
 <P>[Note: there's some CVS work still needed to map the website to an
 area in CVS, so the following paragraph will be expanded after that is
 established]</P>
 <P>For resources that are to be published or linked on the WTP web site,
 there will be an area in CVS that parallels the website, so resources
 that are placed there will be periodically copied to the whosoever for
 proper serving.</P>
 <H2>Streams and Builds</H2>
 <H3>Code into a Build</H3>
 <UL>
 	<LI>Code can go into a build before its part of a milestone plan, since
 	frequent builds are important to stay integrated.</LI>
 	<LI>The component team must be able to do a &quot;local build&quot; (to
 	work out major kinks in definitions and pre-reqs).</LI>

 	<LI>In addition to the code itself being in a build, automated unit
 	tests should also be submitted for the build process.</LI>
 </UL>
 <H3>Nightly, Weekly, Milestone Builds</H3>
 <BLOCKQUOTE>
 <P>Nightly builds will be built from the head stream. Occasional compile
 errors or unit tests failures would not be abnormal, but should be fixed
 by the next nightly build.</P>
 </BLOCKQUOTE>
 <BLOCKQUOTE>
 <P>Weekly integration builds will be built from developer tagged
 versions. There should never be compile errors or unit tests failures in
 an integration build, but if that happens then 1) immediate fixes are
 required and 2) the offender must wear a red clown nose for the day :).
 Integration builds are expected to be of sufficient quality they can be
 used as the target in the development environment, though will have
 received little or no testing.</P>
 </BLOCKQUOTE>
 <BLOCKQUOTE>
 <P>Milestone builds are like weekly integration builds except they get
 substantial testing. The expectation is that milestone builds be of
 sufficient quality that they can be used to self host development.</P>
 </BLOCKQUOTE>
 <H3>Streams, Streams, and more Streams</H3>
 <BLOCKQUOTE>
 <P>Most development should take place in the HEAD stream. However, if a
 component knows its making large breaking changes that would cause
 clients a lot of churn (such as daily changes, to avoid breaking nightly
 build), they can do the major changes in a temporary branch. The
 component team should keep everyone informed that major development is
 occurring in a branch, and naturally, well coordinate the merge back
 into the HEAD stream. A good guideline is that development on a branch
 should not occur for more than 3 weeks without being merged back into
 HEAD.</P>
 </BLOCKQUOTE>
 <H2>Self Assessment</H2>

 <p>The following criteria can be useful to self-measure the success of a
 milestone or release. Component leads should monitor their progress with
 these expectations in mind.</p>
 <ul>
 	<li>Made the date</li>
 	<li>Promised function complete</li>
 	<li>Unit tests and performance tests complete and running as
 	&quot;passed&quot;</li>
 	<li>Test plan with use cases</li>
 	<li>Function available one week before milestone for testing</li>
 	<li>Design and APIs reviewed and issues answered before milestone</li>
 	<li>Community-users buy-in and/or excitement</li>
 	<li>Included community contributed code.</li>
 	<li>All &quot;priority 1&quot; defects resolved and all &quot;severity
 	1&quot; defects addressed.</li>
 </ul>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
	<meta name="GENERATOR" content="IBM Software Development Platform" />
	<link rel="stylesheet" href="http://www.eclipse.org/default_style.css"
	type="text/css" />
	<title>WTP Development Practices</title>
	<!-- David Williams, 10/25/04 (david_williams@us.ibm.com) -->
	</head>

	<body alink="#ff0000" bgcolor="#ffffff" link="#0000ee" text="#000000"
	vlink="#551a8b">

	<table border="0" cellpadding="2" cellspacing="5" width="100%">

	<tbody>
	<tr>

	<td width="60%">
	<p align="LEFT"><FONT size="6"><B><FONT
	face="Verdana, Arial, Helvetica, sans-serif">WTP Development
	Practices</FONT></B></FONT><FONT size="1"><FONT
	face="Arial, Helvetica, sans-serif"><FONT color="#8080ff"><br />
	WTP Development Practices</FONT></FONT></FONT></p>
	</td>


	<td></td>

	<td rowspan="2" width="19%"><img
	src="http://www.eclipse.org/images/Idea.jpg" border="0" height="86"
	width="120" alt="" /></td>

	</tr>


	</tbody>
	</table>
	<p>This document is to describe some guidelines, procedures, and
	"best practices" for doing WTP development. In some cases its
	simply covers consistency/procedure issues, but also recommends best
	practices to help community review and involvement. While all component
	teams can have their own practices, if anyone has some good tips or
	recommendations, please post to wtp-dev for discussion or suggest that
	they be added here.</p>
	<h2>Code into CVS</h2>

	<p>The component developers should provide the following information to
	accompany code checked into CVS. Some of this information will become
	part of the components 'development' directory in cvs, or on the
	component's WTP website, and should be kept up to date as changes take
	place and development progresses. (See <A
	href="#webanddevelopmentresources" target="_self">Web and development
	resources</A> for guidelines on what goes where).</p>

	<ul>
	<li>
	<p>A brief description of the component. This might be an initial
	design document, if it exists, but the actual design document can come
	later. This brief description should overview the function provided by
	the component, but should also list at least a few API's, extension
	points, or other "starting points" for anyone wanting to use
	or extend the component. (See <A href="../wst/components/sse/archiveOfOldish/PluginOverview.html">PluginOverview.html</A>
	for example).</p>
	</li>

	<li>
	<p>A brief initial work plan: describing what development tasks are
	expected for the next milestone or two (or simply in "future"
	if not yet planned for a specific milestone). Specific bugs and feature
	requests can be tracked with bugzilla, but this plan should be given as
	a prose "overview" or highlights of work that is planned
	towards refactoring or making the component "platform
	quality". (See <A href="../wst/components/sse/archiveOfOldish/SSEDevelopmentPlan.html">SSEDevelopmentPlan.html</A>
	for example). In particular, if there are areas that can be explicity
	tagged with "HELP WANTED", that would be good since can help
	let potenital contributors know what areas</p>
	</li>

	<li>
	<p>Each plugin and build feature should contain a 'description' in the
	plugin.xml (or feature.xml) file (there is a description tag for such
	purpose).</p>
	</li>

	<li>
	<p>A plan for how the component will be documented: both the
	"developers guide" type of information (see Platform Plugin
	Developers Guide and JDT Plugin Developers Guide in the base Eclipse
	for examples) and also the status and plan for design overviews and
	"javadoc" type of information.</p>
	</li>

	<li>
	<p>All copyrights and appropriate license files should be correctly
	provided.</p>
	</li>
	<LI><b>CVS Hygiene</b></LI>
	<ul>
	<li>
	<p><B>Team Project Set.</B> Each component team should have a
	"team project set" in their 'development' directory to make
	it easy for others to check out what is needed for that particular
	component.</p>
	</li>

	<li>
	<p><B>Source Folders</B> A minor consistency point: If there's only
	one "source directory" it should be named 'src'. If there's
	more than one, the additional ones should be named similar to
	src-wizards, so its obvious both that's its source, and what its
	conceptual division is. Multiple folders are not typically required,
	but can be handy when one team has responsibility for one part, and
	another team responsibility for another part of the plugin.</p>
	</li>

	<LI>
	<P><B>Compiled code jar.</B> Its recommended the jar for the plugin be
	in the "root" of the plugin. Its also recommended a directory such as
	"runtime" be reserved for those few cases where a pre-existing binary
	jar is shipped with a plugin.</P>
	</LI>

	<li>
	<p><B>cvsignore</B> A .cvsignore file should be provided which has at
	least 'bin' in it to prevent the check in of .class files -- please do
	this before bin is committed to the repository (since you can not
	ignore after its there). Typically, other "transient files"
	(such as a non-custom build.xml, etc) are also added to this
	.cvsignore file.</p>
	</li>

	<li>
	<p><B>Source Formatting</B> Source should be formatted according to
	some stated standard (e.g. see /wtp-jst-home/development/format) and
	appropriate Eclipse compiler options used (e.g. see
	/wtp-jst-home/development/compilersettings) to produce "clean
	code" (no unnecessary casts, no unused imports, etc.) Its also
	recommended the source originally have 'sorted members'. The intent
	here is to have clean, consistent code that makes it easier for others
	to do diffs, compares, and supply patches.</p>
	</li>
	<LI>
	<P><B>Obsolete directories in CVS. </B> If, due to renaming,
	refactoring, or just spelling mistakes, a directory in CVS should
	literally be deleted, to avoid a large of confusing directories,
	please use following procedure. First, if it contains source, its
	recommend to version that plugin's source, with a name such as
	"obsolete<date>". Next delete the source, and leave in
	its place a single file named "obsolete.txt" . If
	appropriate, that file can contain information about why obsolete,
	where the replacement is, etc. Lastly, someone will occasionally delete those directories from CVS (not
	typically an desirable thing to do, since it is a source code control
	system! Note: if some code or project simply become old or outdated, it is usually not appropriate to delete it since it might be required for simple historical reason. In these cases, its recommed to version the final version with some descriptive name like "outdated<date>" and leave a file in the directory called something like "outdated.txt" with some description of when and why, if there's a similar function offered elsewhere, etc. </P>
	</LI>
	</ul>
	</ul>
	<H3>Modified Code into CVS</H3>
	<P>As features are added to bugzilla and fixes done and patches are
	applied, enter the <B>CVS commit comment</B> as<BR>
	<CODE>[BUGNO] Bugzilla abstract or explanation (eg: [6788] Fixed NPE on
	open) </CODE><BR>
	This will allow us to generate a "what is fixed " list
	automatically with links to bugzilla with each build. For an example of
	output in another project, see <BR>
	<A
	href="http://download.eclipse.org/tools/emf/scripts/news-release-notes.php?ver=2.1.0#I200411180800">http://download.eclipse.org/tools/emf/scripts/news-release-notes.php?ver=2.1.0#I200411180800</A><BR>
	</P>
	<H2>Plugin Design Conventions</H2>
	<P><B>Avoid using the export="true" attribute on pre-req
	(imported) plugins</B>.
	</P>
	<P>Its never appropriate to use it just so your upstream clients save
	typing a line in their plugin.xml file. But, sometimes it is appropriate
	to use it -- when the classes/interfaces in pre-req plugin really are
	part of the pre-reqing plugins API. If it fits this later case,
	that is it is part of the plugin's API, please document what part of the API requires it. For example: <BR>
	<CODE> <!-- need to re-export org.eclipse.text since our API depends
	on it, <BR>
	such as IStructuredDocument extends IDocument <BR>
	--> <BR>
	<import plugin="org.eclipse.text"
	export="true"/> </CODE><BR>The reason for this convention is that it forces upstream clients to stay better aware of exactly what they are pre-reqing instead of picking up some classes simply as a side effect of pre-reqing your plugin. </P>
	<h2><A name="webanddevelopmentresources">Web and development resources</A></h2>
	<P>By convention, a directory named 'development' should be used in the
	component's CVS directory structure. This directory would be a peer with
	'features' and 'plugins'. These directories should hold things that may
	be useful or relevant not only to the developers of the components, but
	others interested in contributing (e.g. project team sets, Rose source
	files of designs, etc). Things in these directories are not intended to
	be in a build. If they are intended for an SDK build, they would be part
	of the plugins directory structure.</P>
	<P>[Note: there's some CVS work still needed to map the website to an
	area in CVS, so the following paragraph will be expanded after that is
	established]</P>
	<P>For resources that are to be published or linked on the WTP web site,
	there will be an area in CVS that parallels the website, so resources
	that are placed there will be periodically copied to the whosoever for
	proper serving.</P>
	<H2>Streams and Builds</H2>
	<H3>Code into a Build</H3>
	<UL>
	<LI>Code can go into a build before its part of a milestone plan, since
	frequent builds are important to stay integrated.</LI>
	<LI>The component team must be able to do a "local build" (to
	work out major kinks in definitions and pre-reqs).</LI>

	<LI>In addition to the code itself being in a build, automated unit
	tests should also be submitted for the build process.</LI>
	</UL>
	<H3>Nightly, Weekly, Milestone Builds</H3>
	<BLOCKQUOTE>
	<P>Nightly builds will be built from the head stream. Occasional compile
	errors or unit tests failures would not be abnormal, but should be fixed
	by the next nightly build.</P>
	</BLOCKQUOTE>
	<BLOCKQUOTE>
	<P>Weekly integration builds will be built from developer tagged
	versions. There should never be compile errors or unit tests failures in
	an integration build, but if that happens then 1) immediate fixes are
	required and 2) the offender must wear a red clown nose for the day :).
	Integration builds are expected to be of sufficient quality they can be
	used as the target in the development environment, though will have
	received little or no testing.</P>
	</BLOCKQUOTE>
	<BLOCKQUOTE>
	<P>Milestone builds are like weekly integration builds except they get
	substantial testing. The expectation is that milestone builds be of
	sufficient quality that they can be used to self host development.</P>
	</BLOCKQUOTE>
	<H3>Streams, Streams, and more Streams</H3>
	<BLOCKQUOTE>
	<P>Most development should take place in the HEAD stream. However, if a
	component knows its making large breaking changes that would cause
	clients a lot of churn (such as daily changes, to avoid breaking nightly
	build), they can do the major changes in a temporary branch. The
	component team should keep everyone informed that major development is
	occurring in a branch, and naturally, well coordinate the merge back
	into the HEAD stream. A good guideline is that development on a branch
	should not occur for more than 3 weeks without being merged back into
	HEAD.</P>
	</BLOCKQUOTE>
	<H2>Self Assessment</H2>

	<p>The following criteria can be useful to self-measure the success of a
	milestone or release. Component leads should monitor their progress with
	these expectations in mind.</p>
	<ul>
	<li>Made the date</li>
	<li>Promised function complete</li>
	<li>Unit tests and performance tests complete and running as
	"passed"</li>
	<li>Test plan with use cases</li>
	<li>Function available one week before milestone for testing</li>
	<li>Design and APIs reviewed and issues answered before milestone</li>
	<li>Community-users buy-in and/or excitement</li>
	<li>Included community contributed code.</li>
	<li>All "priority 1" defects resolved and all "severity
	1" defects addressed.</li>
	</ul>
	</body>
	</html>