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