DTP Development Guidelines

← Back to DTP Main Page

Introduction

The purpose of this page is to collect DTP development guidelines and 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 for the DTP 1.5 release. 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.

Background Information

Everyone working on DTP should read and understand the following from the EMO. Note that these areas evolve, so periodic attention to updates is necessary.

• Eclipse IP Policies: A very important part of Eclipse is definition and compliance with Intellectual Property (IP) policies. Here is a good place to start reading about this area. Note that IP violations are viewed very seriously by the community, and could involve legal exposure to all involved parties.
• Eclipse Development Guidelines: Eclipse has established a set of Development Conventions and Guidelines and Development Process. The practices expressed in these documents form a common set of expectations, especially for projects on coordinated releases (Callisto/Europa) such as DTP.
• Eclipse Quality Statement: The Eclipse Quality statement defines expectations for API declarations. Especially for DTP 1.0, we should pay careful attention to this area.

Reoccurring Items

• Component Ownership: DTP components (sets of plug-ins) fall under the responsibility of component leads and their associated project leads. It is very important that you do not change code in DTP CVS (even if technically you have access rights) for other components' plug-ins. Rather, you should contact the plug-in/component/project owner and discuss a solution. The PMC reserves the right to revert any inappropriate source changes due to plug-in ownership. The PMC can also authorize non-component owners to make changes as circumstances dictate.
• Build Environment: DTP must be developed in the correct target platform. Here are the details.
• Open, transparent, and permeable: The direction from the EMO is that all Eclipse projects be open, transparent, and permeable to the greatest extent possible. Ideally, the only difference between being a committer on DTP and not is write access to DTP CVS. In practice it can be hard to make all project activity meet this ideal, but DTP should strive toward it, and every action that is not open, transparent, and permeable should be viewed as sub-optimal.
• Milestone Work Items: All bugs/enhancements expected to be addressed during a release milestone should have that target milestone set in their BugZilla entries. DTP project plans contain queries for each target milestone, and adopters building with DTP often set expectations based on these target dates. Further, coordinated projects such as Callisto and Europa use these queries from projects to convey status and progress. If it turns out that a bug/enhancement can not be addressed within a milestone as previously thought, then the bug/enhancement should be updated with comments explaining why, and a new target milestone should be assigned. It is especially important to avoid having bugs/enhancements for milestones that have already passed, since this means that these items are now not visible for project planning. In brief, such "orphaned" bugs/enhancements unnecessarily create serious project risks, and should be avoided at all times.
• Build Testing: All committers should test DTP builds as often and as thoroughly as possible. Ideally this means synchronizing with nightly builds. An absolute minimum would be around milestone candidates. A couple of points to bear in mind:
  • Even though something works in a development environment, it might not work in the build. The build needs to be tested as a separate entity.
  • Even if you do not change your code, others might make changes that create problems. In a perfect world, all errors would be caught by automated unit tests. Until this perfect world is announced, please know that committer testing remains an important part of keep DTP quaility high.
  • Finding bugs closer to the introduction point often allows for more rapid correction, and prevents needless problems for others in the community. We can only find bugs if we are testing.
• 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. 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 excluded for build distributions.
• Work Item Dependencies: Dependencies between work items should be tracked using standard Bugzilla linking mechanisms, since this is the standard procedure within the Eclipse community. This is especially important for work items that cross projects within DTP and more so for those that cross top-level projects. For example, if a bug in DTP can not be fixed because of an existing bug in the Eclipse platform, then a link for that DTP bug to the platform bug must be entered. This allows those interested to fully understand the dependency chain, and it also alerts DTP committers to when items can be addressed.
• 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.
• API Documentation: JavaDoc and schema documentation for extension points should be updated as necessary to match actual behavior.
• Unit Tests: As new features are added to DTP and bugs fixed, parallel unit tests should also be added for these items.
• Incoming 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. Most importantly:
  • Bugs should be moved out of the general "inbox" state as soon as possible
  • If the bug is not valid, that should be stated and the bug should be closed
  • If the bug is valid, but can not be handled within the current release, reasons should be noted and the bug should be put into a "later" resolution
  • We should be as responsive as possible to comments added to bug reports -- this is the community providing valuable feedback to DTP, and ignoring it will only drive potential users/adopters away from DTP
  • All bugs that do not have a release target milestone set must use the "future" target milestone instead. After a release is complete, each committer should review all "future" bugs and adjust target milestone accordingly for those that will be completed in the next release cycle.
• 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.
• Supporting Documentation: While the value and usage of a component might seem obvious to DTP team members, especially those working on a specific component, those new to DTP or to a particular component will often require further explanation. If brief, people will not use (adopt) what they can not understand, so each committer should make an effort to provide supporting documentation, FAQ, articles, blog postings, etc. for their components.
• 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 a 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.

Non-reoccurring Items

• 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. See the platform's wiki page on this topic for more information.
• Review API Status: As part of a 1.0 release at eclipse.org, we are expected to make API declarations. We need to determine which subsets of DTP are ready, based on Eclipse API policies.
• Back-fill Unit Tests: Currently there is 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.