[svn:parrot] r48193 - trunk/docs/project

[cotto at svn.parrot.org]

Author: cotto
Date: Wed Jul 28 02:39:31 2010
New Revision: 48193
URL: https://trac.parrot.org/parrot/changeset/48193

Log:
update support policy with deprecation notifications

Modified:
   trunk/docs/project/support_policy.pod

Modified: trunk/docs/project/support_policy.pod
==============================================================================
--- trunk/docs/project/support_policy.pod	Tue Jul 27 22:19:42 2010	(r48192)
+++ trunk/docs/project/support_policy.pod	Wed Jul 28 02:39:31 2010	(r48193)
@@ -58,9 +58,12 @@
 features we will also regularly deprecate features and remove them. To
 ease the burden of these changes on the users, our policy is to notify
 users of these deprecations in at least one supported release before
-removal. Deprecation notices are listed in the file L<DEPRECATED.pod>,
-together with a version number to help us track when the feature is safe
-to remove.
+removal and to provide users with a reasonable upgrade path. Deprecation
+notices are listed in the file L<DEPRECATED.pod>, together with a version
+number to help us track when the feature is safe to remove.  The suggested
+upgrade paths for deprecated features can be found on the ParrotDeprecations
+wiki page. Note that deprecation removals that are committed without an
+appropriate upgrade path are subject to reversion.
 
 For example, if a feature exists in Parrot 2.0 (January 2010), and is
 not listed for deprecation in that release, the user can be confident
@@ -77,6 +80,32 @@
 developer release between 2.0 and the next supported release, though we're
 likely to stagger the removals.
 
+=head2 Deprecation Notifications
+
+HLLs, libraries and other users of Parrot will inevitably find that we
+deprecate some core features which they depend on.  In order to minimize the
+pain caused by this deprecation and the subsequent "upgrade tax" (i.e. the time
+users must spend to keep their code working after an upgrade), we now forbid
+the removal of any deprecated feature until an appropriate upgrade path has
+been documented.  Any deprecated features that are removed without an
+appropriate notification are subject to reversion until such notifications have
+been added.  The single (rare) exception to this rule is any core feature which
+is broken or incomplete to the point that it is deemed unusable by any user.
+
+These notifications must be listed on the ParrotDeprecations wiki page, along
+with ticket numbers, a short summary of the deprecation and the expected impact
+on users.  A longer explanation of each deprecation must be put on a page
+dedicated to the deprecations for a specific supported release.  This page
+provides a short description of each change, its rationale and at least one
+example of how affected code can be modified to work after the deprecation
+takes effect.
+
+The purpose of these notifications is to make life easier for users of Parrot.
+If an existing feature is incomplete or broken to the degree that no external
+projects is likely to be able to make use of it, the removal of that feature
+does not require a documented upgrade path.  We expect such deprecations to be
+very rare.
+
 =head2 Experimental Features
 
 From time to time, we may add features to get feedback on their utility and