| <?xml version="1.0" encoding="ISO-8859-1" ?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> |
| <title>WTP code change process</title> |
| </head> |
| <body> |
| |
| <p></p> |
| <h1>WTP code change process</h1> |
| <h2>Background and motivation for this document.</h2> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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 <a href="background.html">background</a> |
| and <a href="projectMakeup.html">project makeup</a> for some details).</p> |
| <p>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.</p> |
| <h2>Changes that are approved in advance</h2> |
| <p>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!</p> |
| <p><b> Bug fixes, java doc and JUnit tests</b> can always be committed |
| to the forward (head) stream.</p> |
| <p><b>Simple feature requests</b>, 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. |
| </p> |
| <p><b>Any evolution of an existing API</b> , as long as the API is evolved in |
| a source and binary compatible way.</p> |
| <h2>Changes that require component team review and agreement</h2> |
| <p>Changes in this section typically require a <a |
| href="defProposal.html">concrete proposal</a>, review, and<a |
| href="defAgreement.html"> prior agreement</a> of <a |
| href="devTeams.html">component team</a> members.</p> |
| <p> |
| 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 <b>how</b> to change or fix something, not whether or not |
| to fix something, or provide some new function. |
| </p> |
| <p><b>New <a href="defAPI.html">API</a></b>. 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.</p> |
| <p><b>Promotion of <a href="defAPI.html">provisional API</a></b>. 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</p> |
| <ul> |
| <li>adopters can move from the provisional API with no churn (or |
| minimal churn, with well documented migration steps)</li> |
| <li>that by moving to the new official API, then "that is |
| it" .... it meets the clients and adopters needs and there would not be |
| additional migration required later on.</li> |
| </ul> |
| <p><b>A change in <a href="defAPI.html">internal non-API</a></b> 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. |
| |
| </p> |
| <h2>Changes that require PMC review and approval</h2> |
| <p><b>Changes to declared API</b>. 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. </p></body> |
| </html> |