blob: daaa1b2e6d06bc7057ba10830745f34fc8f9e8fd [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<meta name="GENERATOR" content="IBM Software Development Platform" />
<link rel="stylesheet" href="" type="text/css" />
<title>WTP Development Practices</title>
<!-- David Williams, 10/25/04 ( -->
<body alink="#ff0000" bgcolor="#ffffff" link="#0000ee" text="#000000" vlink="#551a8b">
<table border="0" cellpadding="2" cellspacing="5" width="100%">
<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 rowspan="2" width="19%"><img src="" border="0" height="86"
width="120" alt="" /></td>
<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
<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>
<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>
<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>
<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>
<p>All copyrights and appropriate license files should be correctly provided.</p>
<li><b>CVS Hygiene</b>
<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>
<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>
<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>
<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>
<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>
<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,
<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=""></a><br>
<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>
<li>Code can go into a build before its part of a milestone plan, since frequent builds are important to stay
<li>The component team must be able to do a &quot;local build&quot; (to work out major kinks in definitions and
<li>In addition to the code itself being in a build, automated unit tests should also be submitted for the
build process.</li>
<h3>Nightly, Weekly, Milestone Builds</h3>
<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>
<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>
<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>
<h3>Streams, Streams, and more Streams</h3>
<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>
<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>
<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>