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.
- Incomming Bugs: As new bugs are registered against DTP, they should be considered for inclusion in DTP 1.0. Each committer should work with a project lead to determine a target milestone.
- Newsgroup & Mailing Lists: As DTP grows in visibility and adoption, it is vital that every DTP committer monitors and participates in the DTP newsgroup and the DTP mailing lists (especially dtp-dev). Even if you do not have time to answer a question fully at the moment, a quick reply saying that you will answer later (and giving a rough time frame) will be appreciated.
- Intellectual Property Issues: Be aware that Eclipse has a substantial set of Intellect Property (IP) rules, and the PMC is required to understand, follow, and enforce these rules. Essentially, any work not done directly by an existing DTP committer should raise questions and be brought to the attention of the PMC. There are procedures to get approvals, but they do take (sometime long) time to complete. Do not wait until the end of a release cycle to ask IP questions, since this likely will mean that the contribution can not be included in the given release.
- 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.