|eclipse web tools platform project
contributing to the wtp project
|This document was inspired by the Contributing to the CDT document|
People often ask, "What does it take to get involved with the development of the WTP?" There are many ways to get involved. On the lightweight end of scale, there is involvement by using the WTP and providing feedback and sharing your experiences on the Eclipse and WTP newsgroups. Beyond that, you can report problems that you discover, so that they may be addressed in future releases. A deeper level of involvement would be to actually solve some of the problems that you or others have uncovered by modifying/writing the necessary code and creating patches that can applied by the project Committers. The final, and most beneficial way to get involved is to take responsibility for a significant piece of development work, whether it's enhancing a particular area of the tool or creating new functionality.
The purpose of this document is to help people and organizations understand what it means to "commit" to WTP Development at this highest level. Basically, it involves a commitment to describe, develop, test and document your contributions.
|Commitment to Development|
Communicating Your Desires/Intentions
The first step involves letting the WTP user community and other WTP development team members what you propose. The mechanism for this is to create Bugzilla entries to describe the enhancements or new capabilities you propose to do. The mailing lists and/or newgroups could also be used for discussing or proposing, in a more informal way, enhancements or new capabilities. Bugzilla is seen here as a central repository of reference for enhancement demands as well as bug reports. All known bug reports should be in Bugzilla. A bug that goes unreported will likely never be fixed.
Bugzilla is the open source change management system used by Eclipse projects. To set these Bugzilla entries apart from other problem reports, Committers should use the word "plan" in the keywords field, and the severity of the entry should be set to "enhancement". Following these guidelines will ensure that all of these proposals get picked up by the appropriate query and recorded in the plan for the upcoming release.
Feature specifications (what your code will do) and design specifications (how it will do it) are an important aspect of the development effort. These specifications will allow the WTP community and the rest of the WTP development team to understand what you are doing and to provide feedback. The format of these documents is not important, the content is.
Contributing Your Code (or other changes)
Every high quality contribution is welcomed, be it from a a Committer or a developer just fixing the one bug they're interested in. A Committer is a developer who has write access to the source code repository for the associated subproject (or component) and has voting rights allowing them to affect the future of the subproject (or component); other developers define patches and submit them, indirectly, through Committers. A developer gains such Committer rights through frequent and consistently valuable contributions to a subproject, or component of a subproject (in the case of large subprojects). For more information in what it means to be or to become an Eclipse project or subproject Committer, see the WTP Project Charter. We should point out that creating and submitting quality patches is the best way to obtain Committer privileges for future work.
Delivering the Code
Once the feature and design documents have been floated to the rest of the WTP community and feedback has been harvested, its time to start pushing the code changes into the development stream. For those that have Committer privileges, these changes can be committed directly into the repository. Those without Committer privileges create patches that get reviewed and applied by Committers. Patch requests are communicated via attachments to Bugzilla bugs. Being a Committer entails certain responsibilities on its own which won't be discussed here.
Patches from non-Committers are generally expected to have been made against the HEAD branch, generated from Eclipse with the Workspace option enabled and in the Unified format. See here for a more complete walkthrough.
Commitment To Testing
Everyone that contributes content to Eclipse projects is expected to test their contributions. When contributing a significant enhancement or feature, that commitment means more than just assuring the community that the code has been tested. It means documenting a test plan and committing to execute that testing on release candidate builds. The Eclipse way of generating releases is to generate a series of release candidate builds after all of the development has been completed. Each release candidate goes through a test-fix cycle where everyone tests their contributions and communicates their findings. A collective decision is made as to which problems will get fixed for the next release candidate, and the process is repeated. Fewer and fewer fixes will be "blessed" as we progress through the release candidates.
So, committing to contribute significant code to the WTP also means committing to participate in the test-fix cycles by executing your test plans against the release candidates build leading up to the final release build.
Commitment to Documentation
An important part of any enhancement or addition to the WTP is making sure that the on-line help of the tool stays current with the changes. The responsibility for updating/modifying/writing the on-line help content that is associated with some part of the tool lies with the contributors of the code. Unless the contributors have commit privileges, the on-line documentation content would get submitted as a patch, much the same as code. And, like code, producing and submitting quality documentation patches is the way to obtain documentation Committer privileges.
Until a Documentation Style Guide is available for the WTP project, you may refer to the CDT Documentation Style Guide to help maintain a constant look and feel for documentation originating from different contributors. There also a couple of links that take you to additional information on how to contribute help content for Eclipse projects.
So, finally, committing to contribute code to the WTP also means committing to contributing the associated on-line documentation content for the part of the tool that is being enhanced or created.