devProcess/devProcess.html

<?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 &quot;prep work&quot; 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 &quot;ok&quot; 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 &quot;new API&quot; 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 &quot;excuse&quot; for leaving bugs unfixed or &quot;not
being able to change&quot; 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 &quot;API Quality
guidelines&quot; 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, &quot;new API&quot;
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 &quot;that is
	it&quot; .... 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 &quot;usage
reports&quot; 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 &quot;evolve&quot; 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 &quot;change in non-API&quot; 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>