| <!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> |
| <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> |
| </li> |
| </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> |
