IMP logo
IMP Manual  for IMP version 2.5.0
deprecation.md
1 Deprecation {#deprecation}
2 ===========
3 
4 Sometimes it is useful to drop support for code for various reasons, for example
5 - it represents a failed experiment
6 - there is better functionality that replaced it
7 - it wasn't used
8 - it is broken and not worth fixing
9 
10 For such code that will be removed, our policy is to mark it as deprecated
11 for one stable release (e.g. 2.1) and then remove it in the next one (2.2).
12 
13 \note If you deprecate code in favor of some new mechanism, it is your
14  responsibility to update all callers of the old code in IMP
15  (C++ code, test cases, examples, benchmarks) to use the new way of
16  doing things, and ensure the test cases still pass.
17 
18 Code that is deprecated must produce warnings when used. (You can also force
19 usage of deprecated code to trigger an exception by calling
20 IMP::set_deprecation_exceptions() or by passing the `--deprecation_exceptions`
21 command line flag.)
22 
23 C++
24 ---
25 
26 C++ code should be marked in the following way (where EXAMPLE is replaced by
27 your module name and 2.1 is replaced by the release where the code is
28 deprecated):
29 - macros should have an `IMPEXAMPLE_DEPRECATED_MACRO(version, replacement)` line added within their definition
30 
31  #define MY_DEPRECATED_MACRO(args) \
32  IMPEXAMPLE_DEPRECATED_MACRO(2.1, "You should use MY_NEW_MACRO(args) instead") \
33  do stuff....
34 
35 - class methods should have `IMPEXAMPLE_DEPRECATED_METHOD_DECL(version)` added to the end of the declaration and `IMPEXAMPLE_DEPRECATED_METHOD_DEF(version, message)` added in their body
36 
37  class IMPEXAMPLEEXPORT MyClass {
38  IMPEXAMPLE_DEPRECATED_METHOD_DECL(2.1)
39  void my_deprecated_method(args) {
40  IMPEXAMPLE_DEPRECATED_METHOD_DEF(2.1, "Use my_new_method(args) instead");
41  do stuff....
42  }
43 
44 - functions should have `IMPEXAMPLE_DEPRECATED_FUNCTION_DECL(version)` added to the end of the declaration and `IMPEXAMPLE_DEPRECATED_FUNCTION_DEF(version, message)` added in their body
45 
46  IMPEXAMPLE_DEPRECATED_FUNCTION_DECL(2.1)
47  void my_deprecated_function(args);
48 
49  void my_deprecated_function(args) {
50  IMPEXAMPLE_DEPRECATED_FUNCTION_DEF(2.1, "Use my_new_function(args) instead");
51  do stuff....
52  }
53 
54 - classes should have `IMPEXAMPLE_DEPRECATED_OBJECT_DECL(version)` or `IMPEXAMPLE_DEPRECATED_VALUE_DECL(version)` added before their constructor declarations and `IMPEXAMPLE_DEPRECATED_OBJECT_DEF(version, message)` or `IMPEXAMPLE_DEPRECATED_VALUE_DEF(version, message)` added in their constructor bodies.
55 
56  class IMPEXAMPLEEXPORT MyDeprecatedClass :: public IMP::Object {
57  public:
58  IMPEXAMPLE_DEPRECATED_OBJECT_DECL(2.1)
59  MyDeprecatedClass(args) {
60  IMPEXAMPLE_DEPRECATED_OBJECT_DEF(2.1, "Use MyNewClass instead");
61  }
62  IMPEXAMPLE_DEPRECATED_OBJECT_DECL(2.1)
63  MyDeprecatedClass(other_args) {
64  IMPEXAMPLE_DEPRECATED_OBJECT_DEF(2.1, "Use MyNewClass instead");
65  }
66  };
67 
68 - Headers should have `IMPEXAMPLE_DEPRECATED_HEADER(version, message)` in them.
69 
70  #ifndef IMP_MY_DEPRECATED_HEADER_H
71  #define IMP_MY_DEPRECATED_HEADER_H
72  IMPEXAMPLE_DEPREACTED_HEADER(2.1, "Use my_new_header.h")
73  ...
74  #endif // IMP_MY_DEPRECATED_HEADER_H
75 
76 
77 - All things should also use the `\deprecated_at` doxygen macro in their docs:
78 
79  /** \deprecated_at{2.1} Replaced by my_new_function(). */
80 
81 These will provide documentation, and runtime and compile time warning messages to users.
82 
83 Python
84 ------
85 
86 For Python code, we provide similar functions and decorators to mark methods,
87 classes, methods, or functions as deprecated:
88 
89  IMP.deprecated_module("2.1", __name__, "Use my_new_module instead")
90 
91  @IMP.deprecated_object("2.1", "Use MyNewClass instead")
92  class MyClass(object):
93  @IMP.deprecated_method("2.1", "Use my_new_method(args) instead")
94  def my_deprecated_method(self):
95  do stuff...
96 
97  @IMP.deprecated_function("2.1", "Use my_new_function(args) instead")
98  def my_deprecated_function(args):
99  do stuff...
100 
101 For Python there is no need to use the `\deprecated_at` macro - the
102 warning message from the decorator is automatically added to the documentation.
103 
104 Tests and examples
105 ------------------
106 
107 Any code that demonstrates the use of IMP should not rely on deprecated
108 functionality. This includes tests, examples, and benchmarks.
109 
110 All examples run as part of the IMP test suite get passed the
111 `--deprecation_exceptions` command line flag. Thus, any example that calls
112 IMP.setup_from_argv() or uses IMP.OptionParser will fail if it tries to
113 call deprecated code. It is highly recommended that all examples do this.
114 
115 All unit tests that call IMP.test.main() will also trigger exceptions if they
116 try to call deprecated code. If for some reason you need to test a deprecated
117 code pathway, use the IMP.allow_deprecated()
118 [context manager](http://eigenhombre.com/2013/04/20/introduction-to-context-managers/) as follows:
119 
120  with IMP.allow_deprecated():
121  my_deprecated_function()