This process was written and approved by the WTP in October of 2006. It is meant as simply as a small evolution and improvement of our existing processes and primarily as providing documentation for those processes.
WTP is mature enough now, and is being used by enough companies for business critical applications, that the WTP PMC thought it best to write down our agreed to procedures and decision process.
Our WTP Charter, and the The Eclipse general charter it refers to, specifies the general procedure and decision process used for changing code, and it specifies the PMC should establish the details appropriate to the project. (See background and project makeup for some details).
This process is pretty much how we have already been operating, except that moving forward we need to do more "prep work" in side branches, before committing to a release or a milestone. This allows better review, before being committed, and allows for details to be worked out and iterated in the side branch, so that once an adopter sees it in a build (and may have to react to it) it is pretty much a finished work, not something that would change a lot from week to week or milestone to milestone.
The following types of changes do not require development in a side branch, and no particular review or voting, etc. But, any changes should be associated with some bugzilla entry to allow better historical tracking. In general, internal changes for the sake of better, faster, simpler and cleaner components are not only "ok" but are greatly encouraged!
Bug fixes, java doc and JUnit tests can always be committed to the forward (head) stream.
Simple feature requests, if simple additions, that do not increase plugin dependancies, or require changes in APIs, and have no effect on known usage by adopters (from usage reports). Any new features that involve API or SPI would fall in the "new API" category below.
Any evolution of an existing API , as long as the API is evolved in a source and binary compatible way.
Changes in this section typically require a concrete proposal, review, and prior agreement of component team members.
All these control processes are simply to protect the stability of our code base and the investment made by clients which adopt our code. It is not intended to ever be an "excuse" for leaving bugs unfixed or "not being able to change" code. It is always only a question of how to change or fix something, not whether or not to fix something, or provide some new function.
New API. The main criteria here is if it meets "API Quality guidelines" as described in the Eclipse Development Process and allows for later API evolution. The committers for a component (and their clients) are the primary stake holders, and thus is their responsibility to propose and decide API and ensure its quality. But, it should be developed in a side branch where it can be better reviewed and assessed before being committed to a build.
Promotion of provisional API. While the main decision is up to committers of a component (and follows normal, "new API" guidelines above) the additional type of criteria the PMC requires for provisional API is that
A change in internal non-API that is clearly identified in "usage reports" as being used by adopters. Any such proposed changes needs approval of the component team and be open to public review so that adopters can comment, and anticipate and minimize disruption. The best option, is to "evolve" the non-API so it does not impact adopters. But, if that's not possible or feasible, a typical part of such a proposal would include what migration would involve .... such as a package rename only, argument changes, or a rework of fundamental logic. Note: a "change in non-API" in this sense includes changes in behavior such as threading behavior, order of execution, etc., not just changes in signatures.
Changes to declared API. This is nearly never allowed. But, there is, judging from history, times when it should be considered as an option, either to acknowledge some previous fundamental mistake for which no other reasonable solution can be found. Or, more likely, sometimes an API is specified in a mistaken or ambiguous way, so some change might be interpreted by some as a change in behavior, but some might be argued that it is not, based on the original intent. These sorts of cases, once there is agreement among the component team, must be brought forward to the PMC for approval so the cost-benefit balance can be properly weighed.