devProcess/devProcess.html - gerrit/www.eclipse.org/webtools - Git at Google

 <?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>
	<?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>