src/site/xdoc/development/deprecation.xml - maven-site - Git at Google

 <?xml version="1.0"?>
 <!--
 /*
  * Copyright 2001-2004 The Apache Software Foundation.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
  -->


 <document>
   <properties>
     <title>Deprecation Policy</title>
     <author email="jon@latchkey.com">Jon S. Stevens</author>
    </properties>

    <body>

  <section name="Deprecation Policy">
  <p>
  In order for people to be comfortable with development of code based on
  your project and not have to constantly worry about the rug being pulled out
  from underneath them, we have instituted the following policy. Our goal
  is to take this matter as an extremely serious practice.
  </p>
  </section>

  <section name="The Rules">
 <p>
 <ol>
 <li>
 <strong>ALL</strong> existing class and method modification needs to go
 through a deprecation phase. We realize that this may make some of the
 API code look a bit ugly when you look at the source code, but this is a
 MUST have. It is recommend that developers who deprecate methods move
 them to the bottom of the .java file.
 </li>

 <li>
 <p>
 The amount of time between deprecation and removal must be at least one
 release of your project. It could be more than one version release before the
 deprecated item is removed, but it cannot be less than one version
 release. In other words, we can deprecate something in 2.1 and remove it
 in the release of 2.1.1. The amount of time between 2.1 and 2.1.1 could
 be measured in days, not months. Discussion will occur on the mailing
 list pertaining to the real number of versions between deprecation and
 removal. You will have a chance to express your concerns and we will
 take them into consideration. Most likely a major feature change will
 not be removed between a 2.1 and 2.1.1 release. Instead, we would wait
 until 2.2 to remove the deprecated items in that case.
 </p>

 <p>
 The reason why we do not feel that time is of importance is because 6
 months may not be a long enough time for a project to keep up and 2
 weeks might be fine for another project. By focusing on deprecation
 through releases, people can choose to code against a specific version
 of your project and feel comfortable that their code will compile for at
 least one released version. This also gives people the chance to compile
 against various previous releases to do incremental upgrades and find
 out what will break in the next release.
 </p>
 </li>

 <li>
 Any time a method is deprecated, notification <strong>MUST</strong> be
 sent to the developer mailing list documenting the methods that have
 been deprecated as well as the alternative use. This will allow people
 to search the archives and find out when and why a method was deprecated
 as well as the procedure for upgrading to the latest methodology.
 </li>

 <li>
 Items that are not Java code related and cannot be deprecated (such as
 property key changes and DTD modifications) must be documented on the
 mailing list.
 </li>

 <li>
 All documentation must be updated at the time of modification to reflect
 the latest status of the code.
 </li>

 <li>
 Any patches or commits that do not follow these rules will be rejected
 and it is up to the person who has either checked in the modifications
 or sent the patch to submit a new patch, fix the problem or back the
 code out of CVS.
 </li>

 </ol>

 </p>

  </section>
  <section name="Developers: Suggestions for following The Rules">
  <p>
  When changing the signature of a public or protected method or class,
  this has the potential of breaking someones code who depends on the
  method or class. Since we are developing Open Source software, there is
  absolutely no way we can tell if someone is using our code or not.
  Therefore, in order to minimize the effect of changes, it is possible
  to use the concept of deprecation. When working on code, keep in mind
  the following guidelines:
  </p>

  <p>
     <ul>
         <li>
         When modifying an existing public or protected method or class
         first mark the existing method as deprecated and create a new
         one to replace the old one.
         </li>
         <li>
         Do not remove any public or protected classes/interfaces that
         have any chance of being used outside of the application.
         Instead, mark them as deprecated.
         </li>
         <li>
         When migrating code from one package to another, deprecate the
         old package and then have the old code reference the new code as
         a thin temporary wrapper. The deprecation tells people that the
         wrapper will be going away at some point in the future.
         </li>
         <li>
         Changes to configuration files needs to be well documented so
         that people can have a laundry list of foo->bar conversions.
         </li>
         <li>
         When changing a database schema, make sure to provide ALTER
         TABLE statements to modify the schema so that people can convert
         their existing databases easily.
         </li>
     </ul>
  </p>
  </section>

  </body>
 </document>
	<?xml version="1.0"?>
	<!--
	/*
	* Copyright 2001-2004 The Apache Software Foundation.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/
	-->


	<document>
	<properties>
	<title>Deprecation Policy</title>
	<author email="jon@latchkey.com">Jon S. Stevens</author>
	</properties>

	<body>

	<section name="Deprecation Policy">
	<p>
	In order for people to be comfortable with development of code based on
	your project and not have to constantly worry about the rug being pulled out
	from underneath them, we have instituted the following policy. Our goal
	is to take this matter as an extremely serious practice.
	</p>
	</section>

	<section name="The Rules">
	<p>
	<ol>
	<li>
	<strong>ALL</strong> existing class and method modification needs to go
	through a deprecation phase. We realize that this may make some of the
	API code look a bit ugly when you look at the source code, but this is a
	MUST have. It is recommend that developers who deprecate methods move
	them to the bottom of the .java file.
	</li>

	<li>
	<p>
	The amount of time between deprecation and removal must be at least one
	release of your project. It could be more than one version release before the
	deprecated item is removed, but it cannot be less than one version
	release. In other words, we can deprecate something in 2.1 and remove it
	in the release of 2.1.1. The amount of time between 2.1 and 2.1.1 could
	be measured in days, not months. Discussion will occur on the mailing
	list pertaining to the real number of versions between deprecation and
	removal. You will have a chance to express your concerns and we will
	take them into consideration. Most likely a major feature change will
	not be removed between a 2.1 and 2.1.1 release. Instead, we would wait
	until 2.2 to remove the deprecated items in that case.
	</p>

	<p>
	The reason why we do not feel that time is of importance is because 6
	months may not be a long enough time for a project to keep up and 2
	weeks might be fine for another project. By focusing on deprecation
	through releases, people can choose to code against a specific version
	of your project and feel comfortable that their code will compile for at
	least one released version. This also gives people the chance to compile
	against various previous releases to do incremental upgrades and find
	out what will break in the next release.
	</p>
	</li>

	<li>
	Any time a method is deprecated, notification <strong>MUST</strong> be
	sent to the developer mailing list documenting the methods that have
	been deprecated as well as the alternative use. This will allow people
	to search the archives and find out when and why a method was deprecated
	as well as the procedure for upgrading to the latest methodology.
	</li>

	<li>
	Items that are not Java code related and cannot be deprecated (such as
	property key changes and DTD modifications) must be documented on the
	mailing list.
	</li>

	<li>
	All documentation must be updated at the time of modification to reflect
	the latest status of the code.
	</li>

	<li>
	Any patches or commits that do not follow these rules will be rejected
	and it is up to the person who has either checked in the modifications
	or sent the patch to submit a new patch, fix the problem or back the
	code out of CVS.
	</li>

	</ol>

	</p>

	</section>
	<section name="Developers: Suggestions for following The Rules">
	<p>
	When changing the signature of a public or protected method or class,
	this has the potential of breaking someones code who depends on the
	method or class. Since we are developing Open Source software, there is
	absolutely no way we can tell if someone is using our code or not.
	Therefore, in order to minimize the effect of changes, it is possible
	to use the concept of deprecation. When working on code, keep in mind
	the following guidelines:
	</p>

	<p>
	<ul>
	<li>
	When modifying an existing public or protected method or class
	first mark the existing method as deprecated and create a new
	one to replace the old one.
	</li>
	<li>
	Do not remove any public or protected classes/interfaces that
	have any chance of being used outside of the application.
	Instead, mark them as deprecated.
	</li>
	<li>
	When migrating code from one package to another, deprecate the
	old package and then have the old code reference the new code as
	a thin temporary wrapper. The deprecation tells people that the
	wrapper will be going away at some point in the future.
	</li>
	<li>
	Changes to configuration files needs to be well documented so
	that people can have a laundry list of foo->bar conversions.
	</li>
	<li>
	When changing a database schema, make sure to provide ALTER
	TABLE statements to modify the schema so that people can convert
	their existing databases easily.
	</li>
	</ul>
	</p>
	</section>

	</body>
	</document>