DTP Ganymede 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 Ganymede 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.

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.
• Avoiding Discouraged Access Warnings: A Discouraged Access warning says that you are using code that is considered internal to another component. Doing so injects risk of future, uncontrolled breakage in DTP, because internal code is allowed to vary without notification to the adopter community. If the warning is because of referencing DTP code, then you should work with DTP team members on the target component to resolve the issue. If the component is external to DTP then you should:
  • Contact the component team, using the appropriate newsgroup or mailing list. Explain what you are trying to do, and ask for alternatives to avoid the warning.
  • If an alternative exists, refactor the code to use the appropriate method.
  • If an alternative does not exist, open a bug for the target component asking for API support in that area, and document DTP usage of the internal code.
• Plug-in version updates: When any change is made to a plug-in, some part of its version stamp must be updated. At a minimum, the version qualifier will be updated to reflect the current date (and change iteration). Refer to the Plug-in Version Policy for details.
• 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 Ganymede plug-ins must use a manifest.mf descriptor.
• About file inclusion: All DTP Ganymede plug-ins must include the approved about.html file.
• Plug-in and Vendor Names: All DTP Ganymede 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 Ganymede 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 Ganymede. 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.
• NEW! Model Folders: For those plug-in projects with EMF or other models that may be extended that are not explicitly part of the source for the plug-in (i.e. a separate "Model" folder containing XSDs, ecores, genmodel files, and so on), the "Model" folder should be included in the Binary build configuration as well as the Source configuration to enable adopters to extend them more easily.

Non-reoccurring Items

• Resolve Discouraged Access Warnings: DTP 1.5 has a number of Discouraged Access warnings, fortunately, the vast majority of which are due to references within the DTP project itself. In DTP Ganymede we should make it a goal to resolve these warnings by adding the correct access specifications to DTP plug-ins and refactoring to remove discouraged external usage. If there are cases that can not be resolved before the DTP Ganymede release, we should document these on a separate wiki page to alert adopters of the risks present in this area.
• 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.