Rev 2826: Developer docs about deprecation in http://sourcefrog.net/bzr/trivial

[Martin Pool]

At http://sourcefrog.net/bzr/trivial

------------------------------------------------------------
revno: 2826
revision-id: mbp at sourcefrog.net-20070917034746-buzi0gf7uptisz4y
parent: pqm at pqm.ubuntu.com-20070917005035-cshdkpzbj63id1uw
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: trivial
timestamp: Mon 2007-09-17 13:47:46 +1000
message:
  Developer docs about deprecation
modified:
  doc/developers/HACKING.txt     HACKING-20050805200004-2a5dc975d870f78c
=== modified file 'doc/developers/HACKING.txt'
--- a/doc/developers/HACKING.txt	2007-09-10 10:05:51 +0000
+++ b/doc/developers/HACKING.txt	2007-09-17 03:47:46 +0000
@@ -621,6 +621,27 @@
 callers will at least get an AttributeError rather than weird results.
 
 
+Deprecation decorators
+----------------------
+
+``bzrlib.symbol_versioning`` provides decorators that can be attached to
+methods, functions, and other interfaces to indicate that they should no
+longer be used.
+
+To deprecate a static method this invocation is needed, in this particular
+order::
+
+    @staticmethod
+    @deprecated_function(zero_ninetyone)
+    def create_repository(base, shared=False, format=None):
+
+When you deprecate an API, you should not just delete its tests, because
+then we might introduce bugs in them.  If the API is still present at all,
+it should still work.  The basic approach is to use
+``TestCase.applyDeprecated`` which in one step checks that the API gives
+the expected deprecation message, and also returns the real result from
+the method, so that tests can keep running.
+
 Coding Style Guidelines
 =======================