blob: 5dc74a5b75622cbecf8c8a175bbfbe05766b814a [file] [log] [blame]
ryman91c13072004-12-08 19:18:10 +00001<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
4<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
5<meta name="GENERATOR" content="IBM Software Development Platform" />
6<link rel="stylesheet" href=""
7 type="text/css" />
8<title>WTP Development Practices</title>
9<!-- David Williams, 10/25/04 ( -->
12<body alink="#ff0000" bgcolor="#ffffff" link="#0000ee" text="#000000"
13 vlink="#551a8b">
15<table border="0" cellpadding="2" cellspacing="5" width="100%">
17 <tbody>
18 <tr>
20 <td width="60%">
21 <p align="LEFT"><FONT size="6"><B><FONT
22 face="Verdana, Arial, Helvetica, sans-serif">WTP Development
23 Practices</FONT></B></FONT><FONT size="1"><FONT
24 face="Arial, Helvetica, sans-serif"><FONT color="#8080ff"><br />
25 WTP Development Practices</FONT></FONT></FONT></p>
26 </td>
29 <td></td>
31 <td rowspan="2" width="19%"><img
32 src="" border="0" height="86"
33 width="120" alt="" /></td>
35 </tr>
38 </tbody>
40<p>This document is to describe some guidelines, procedures, and
41&quot;best practices&quot; for doing WTP development. In some cases its
42simply covers consistency/procedure issues, but also recommends best
43practices to help community review and involvement. While all component
44teams can have their own practices, if anyone has some good tips or
45recommendations, please post to wtp-dev for discussion or suggest that
46they be added here.</p>
47<h2>Code into CVS</h2>
49<p>The component developers should provide the following information to
50accompany code checked into CVS. Some of this information will become
51part of the components 'development' directory in cvs, or on the
52component's WTP website, and should be kept up to date as changes take
53place and development progresses. (See <A
54 href="#webanddevelopmentresources" target="_self">Web and development
55resources</A> for guidelines on what goes where).</p>
58 <li>
59 <p>A brief description of the component. This might be an initial
60 design document, if it exists, but the actual design document can come
61 later. This brief description should overview the function provided by
62 the component, but should also list at least a few API's, extension
63 points, or other &quot;starting points&quot; for anyone wanting to use
64 or extend the component. (See <A href="sse/PluginOverview.html">PluginOverview.html</A>
65 for example).</p>
66 </li>
68 <li>
69 <p>A brief initial work plan: describing what development tasks are
70 expected for the next milestone or two (or simply in &quot;future&quot;
71 if not yet planned for a specific milestone). Specific bugs and feature
72 requests can be tracked with bugzilla, but this plan should be given as
73 a prose &quot;overview&quot; or highlights of work that is planned
74 towards refactoring or making the component &quot;platform
75 quality&quot;. (See <A href="sse/SSEDevelopmentPlan.html">SSEDevelopmentPlan.html</A>
76 for example). In particular, if there are areas that can be explicity
77 tagged with &quot;HELP WANTED&quot;, that would be good since can help
78 let potenital contributors know what areas</p>
79 </li>
81 <li>
82 <p>Each plugin and build feature should contain a 'description' in the
83 plugin.xml (or feature.xml) file (there is a description tag for such
84 purpose).</p>
85 </li>
87 <li>
88 <p>A plan for how the component will be documented: both the
89 &quot;developers guide&quot; type of information (see Platform Plugin
90 Developers Guide and JDT Plugin Developers Guide in the base Eclipse
91 for examples) and also the status and plan for design overviews and
92 &quot;javadoc&quot; type of information.</p>
93 </li>
95 <li>
96 <p>All copyrights and appropriate license files should be correctly
97 provided.</p>
98 </li>
99 <LI><b>CVS Hygiene</b></LI>
100 <ul>
101 <li>
102 <p><B>Team Project Set.</B> Each component team should have a
103 &quot;team project set&quot; in their 'development' directory to make
104 it easy for others to check out what is needed for that particular
105 component.</p>
106 </li>
108 <li>
109 <p><B>Source Folders</B> A minor consistency point: If there's only
110 one &quot;source directory&quot; it should be named 'src'. If there's
111 more than one, the additional ones should be named similar to
112 src-wizards, so its obvious both that's its source, and what its
113 conceptual division is. Multiple folders are not typically required,
114 but can be handy when one team has responsibility for one part, and
115 another team responsibility for another part of the plugin.</p>
116 </li>
118 <LI>
119 <P><B>Compiled code jar.</B> Its recommended the jar for the plugin be
120 in the "root" of the plugin. Its also recommended a directory such as
121 "runtime" be reserved for those few cases where a pre-existing binary
122 jar is shipped with a plugin.</P>
123 </LI>
125 <li>
126 <p><B>cvsignore</B> A .cvsignore file should be provided which has at
127 least 'bin' in it to prevent the check in of .class files -- please do
128 this before bin is committed to the repository (since you can not
129 ignore after its there). Typically, other &quot;transient files&quot;
130 (such as a non-custom build.xml, etc) are also added to this
131 .cvsignore file.</p>
132 </li>
134 <li>
135 <p><B>Source Formatting</B> Source should be formatted according to
136 some stated standard (e.g. see /wtp-jst-home/development/format) and
137 appropriate Eclipse compiler options used (e.g. see
138 /wtp-jst-home/development/compilersettings) to produce &quot;clean
139 code&quot; (no unnecessary casts, no unused imports, etc.) Its also
140 recommended the source originally have 'sorted members'. The intent
141 here is to have clean, consistent code that makes it easier for others
142 to do diffs, compares, and supply patches.</p>
143 </li>
144 <LI>
145 <P><B>Obsolete directories in CVS. </B> If, due to renaming,
146 refactoring, or just spelling mistakes, a directory in CVS should
147 literally be deleted, to avoid a large of confusing directories,
148 please use following procedure. First, if it contains source, its
149 recommend to version that plugin's source, with a name such as
150 &quot;obsolete&lt;date&gt;&quot;. Next delete the source, and leave in
151 its place a single file named &quot;obsolete.txt&quot; . If
152 appropriate, that file can contain information about why obsolete,
153 where the replacement is, etc. Lastly, someone will occasionally delete those directories from CVS (not
154 typically an desirable thing to do, since it is a source code control
155 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>
156 </LI>
157 </ul>
159<H3>Modified Code into CVS</H3>
160<P>As features are added to bugzilla and fixes done and patches are
161applied, enter the <B>CVS commit comment</B> as<BR>
162<CODE>[BUGNO] Bugzilla abstract or explanation (eg: [6788] Fixed NPE on
163open) </CODE><BR>
164This will allow us to generate a &quot;what is fixed &quot; list
165automatically with links to bugzilla with each build. For an example of
166output in another project, see <BR>
168 href=""></A><BR>
170<H2>Plugin Design Conventions</H2>
171<P><B>Avoid using the export=&quot;true&quot; attribute on pre-req
172(imported) plugins</B>.
174<P>Its never appropriate to use it just so your upstream clients save
175typing a line in their plugin.xml file. But, sometimes it is appropriate
176to use it -- when the classes/interfaces in pre-req plugin really are
177part of the pre-reqing plugins API. If it fits this later case,
178that is it is part of the plugin's API, please document what part of the API requires it. For example: <BR>
179<CODE> &lt;!-- need to re-export org.eclipse.text since our API depends
180on it, <BR>
181such as IStructuredDocument extends IDocument <BR>
182--&gt; <BR>
183&lt;import plugin=&quot;org.eclipse.text&quot;
184export=&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>
185<h2><A name="webanddevelopmentresources">Web and development resources</A></h2>
186<P>By convention, a directory named 'development' should be used in the
187component's CVS directory structure. This directory would be a peer with
188'features' and 'plugins'. These directories should hold things that may
189be useful or relevant not only to the developers of the components, but
190others interested in contributing (e.g. project team sets, Rose source
191files of designs, etc). Things in these directories are not intended to
192be in a build. If they are intended for an SDK build, they would be part
193of the plugins directory structure.</P>
194<P>[Note: there's some CVS work still needed to map the website to an
195area in CVS, so the following paragraph will be expanded after that is
197<P>For resources that are to be published or linked on the WTP web site,
198there will be an area in CVS that parallels the website, so resources
199that are placed there will be periodically copied to the whosoever for
200proper serving.</P>
201<H2>Streams and Builds</H2>
202<H3>Code into a Build</H3>
204 <LI>Code can go into a build before its part of a milestone plan, since
205 frequent builds are important to stay integrated.</LI>
206 <LI>The component team must be able to do a &quot;local build&quot; (to
207 work out major kinks in definitions and pre-reqs).</LI>
209 <LI>In addition to the code itself being in a build, automated unit
210 tests should also be submitted for the build process.</LI>
212<H3>Nightly, Weekly, Milestone Builds</H3>
214<P>Nightly builds will be built from the head stream. Occasional compile
215errors or unit tests failures would not be abnormal, but should be fixed
216by the next nightly build.</P>
219<P>Weekly integration builds will be built from developer tagged
220versions. There should never be compile errors or unit tests failures in
221an integration build, but if that happens then 1) immediate fixes are
222required and 2) the offender must wear a red clown nose for the day :).
223Integration builds are expected to be of sufficient quality they can be
224used as the target in the development environment, though will have
225received little or no testing.</P>
228<P>Milestone builds are like weekly integration builds except they get
229substantial testing. The expectation is that milestone builds be of
230sufficient quality that they can be used to self host development.</P>
232<H3>Streams, Streams, and more Streams</H3>
234<P>Most development should take place in the HEAD stream. However, if a
235component knows its making large breaking changes that would cause
236clients a lot of churn (such as daily changes, to avoid breaking nightly
237build), they can do the major changes in a temporary branch. The
238component team should keep everyone informed that major development is
239occurring in a branch, and naturally, well coordinate the merge back
240into the HEAD stream. A good guideline is that development on a branch
241should not occur for more than 3 weeks without being merged back into
244<H2>Self Assessment</H2>
246<p>The following criteria can be useful to self-measure the success of a
247milestone or release. Component leads should monitor their progress with
248these expectations in mind.</p>
250 <li>Made the date</li>
251 <li>Promised function complete</li>
252 <li>Unit tests and performance tests complete and running as
253 &quot;passed&quot;</li>
254 <li>Test plan with use cases</li>
255 <li>Function available one week before milestone for testing</li>
256 <li>Design and APIs reviewed and issues answered before milestone</li>
257 <li>Community-users buy-in and/or excitement</li>
258 <li>Included community contributed code.</li>
259 <li>All &quot;priority 1&quot; defects resolved and all &quot;severity
260 1&quot; defects addressed.</li>