[Checkins] SVN: Sandbox/philikon/foundation/maintaining-software.txt Write down policy on backward incompatible changes, loosely based on

[Philipp von Weitershausen]

Log message for revision 79272:
  Write down policy on backward incompatible changes, loosely based on
  http://mail.zope.org/pipermail/zope3-dev/2007-August/023364.html
  

Changed:
  U   Sandbox/philikon/foundation/maintaining-software.txt

-=-
Modified: Sandbox/philikon/foundation/maintaining-software.txt
===================================================================
--- Sandbox/philikon/foundation/maintaining-software.txt	2007-08-25 22:35:07 UTC (rev 79271)
+++ Sandbox/philikon/foundation/maintaining-software.txt	2007-08-26 00:19:03 UTC (rev 79272)
@@ -180,6 +180,36 @@
 .. _doctests: http://docs.python.org/lib/module-doctest.html
 
 
+Backward-compatibility
+----------------------
+
+As a rule of thumb, backwards-incompatible changes to stable, released
+code should be avoided.  Examples of backwards-incompatible changes
+are
+
+* renaming packages, modules, classes, functions, etc. without
+  ensuring the old import paths still work,
+
+* changing a public interface, which also includes *adding* attributes
+  or methods (imagine people implemented this interface in their own
+  code, now all of a sudden their implementations don't comply with
+  the interface anymore)
+
+If you'd like to replace a certain component or package with another,
+better one, don't remove the original component or package, not even
+after a deprecation period.  Instead, consider simply abandoning the
+original component or package.  You should clearly document that, of
+course, possibly even by raising DeprecationWarnings.  Then you
+provide the replacement under a separate name.
+
+For example, consider you would like to radically improve a package
+``mycorp.foo``.  Instead of changing it in an incompatible way, you
+should just stop supporting it and create ``mycorp.newfoo`` (or
+whatever you'd like to name it).
+
+Consistency weighs higher than cleanliness.
+
+
 Package documentation and metadata
 ----------------------------------
 
@@ -373,6 +403,4 @@
 
 * version numbering schemes,
 
-* how to deal with package dependencies,
-
-* the policy on backward compatibility and deprecation.
+* how to deal with package dependencies.