DTP Development Guidelines
The purpose of this page is to collect DTP 1.0 work items in a convenient list for reference by DTP committers and especially DTP project leads. This list contains both reoccurring and non-reoccurring work items. Reoccurring work items are those which require action a multiple times during the project, while non-reoccurring work items are completed by being addressed once.
- Plug-in version updates: When any change to a plug-in is made, regardless of whether the change is to source code or other project elements, the last (fourth place) number in the plug-in version must be updated as well. For DTP, this almost always means updating the version in the build.properties files as well. Details as follows:
- Why? Because otherwise there is no easy way of determining which plug-ins have changed between builds based on the binary distributions.
- Version format: major.minor.service.date_stamp. The date_stamp is what should be updated with each plug-in change. The format for this is YearMonthDateBuildIteration. For example, if the current date is October 2, 2006, then the date_stamp is 200610021. The reason for the BuildIteration number at the end of the date_stamp (in the example, it is 1), is so we can accomodate multiple plug-in changes on one day. Thus, the second change to a plug-in on October 2, 2006 would result in a date_stamp of 200610022. This BuildIteration flag is particularly important near release time, when multiple builds per day might be posted to address major bugs.
- Do not update any other version fields unless you obtain permission from dtp-pmc (that is, at least 2 "yes" votes). In the future, a more comprehensive versioning plan for DTP will provide policies governing the update other fields other than date_stamp.
- Version Tolerance Specifications for Dependencies: All plug-ins that any DTP plug-in depends on (as specified in the manifest.mf descriptor) must also include a version tolerance specification.
- Build Dependencies: Any changes in plug-in dependencies must be reported to John, or else it is likely that the next build will fail. Normally John attempts to fix broken dependencies in build files, but pressure near release dates might make this impossible, and hence broken plug-ins will be exluded for build distributions.
- API Documentation: JavaDoc and schema documentation for extension points should be updated as necessary to make actual behavior.
- Unit Tests: As new features are added to DTP and bugs fixed, parallel unit tests should also be added for these items.
- Manifest file usage: All DTP 1.0 plug-ins must use a manifest.mf descriptor.
- About file inclusion: All DTP 1.0 plug-ins must include the approved about.html file.
- Plug-in and Vendor Names: All DTP 1.0 plug-ins must use Eclipse.org as the vendor name reported in the Eclipse About... dialog. The plug-in name and description should be consistent with other DTP 1.0 plug-ins. As always, ask dtp-pmc if there is any doubt.
- Jar Plug-ins: It is expected that Eclipse project distribute plug-ins as single jars whenever possible. DTP 0.9.x made strides toward this goal, but there still are too many plug-ins that could be jarred. For DTP 1.0, all plug-ins that can be jarred should be. A separate page will be created and linked here to track this item.
- Use Cases for API: In team meetings, it was agreed that each DTP project team would create use cases on the Wiki covering their API proposed for DTP 1.0. The agreed deadline for this item was Monday, October 16. It is very important that this step is completed, since it represents the first step in a full API review for DTP 1.0. API and extension points not represented by use cases by the deadline will not be considered for exposure as provisional or platform API in DTP 1.0.
- Back-fill Unit Tests: Currently there are a number of plug-ins in DTP that do not have sufficient unit test coverage. Project leads should work with their teams to ensure that unit tests are added for these cases. A separate page will be created and linked here to track this item.