Deprecation Process#

This page documents how to deprecate an API and mark it as no longer necessary for downstream consumers of VTK.

Deprecating classes and functions#

Classes, functions, member functions and member variables may be deprecated using the deprecation macros.

#include "vtkDeprecation.h" // Include the macros.

// A deprecated class.
class VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation") OPT_EXPORT_MACRO oldClass {
public:
  // A deprecated member function.
  VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation")
  void oldMemberFunction();
};

// A deprecated function.
VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation")
void oldFunction();

The X_Y_Z should be the newest macro available in the vtkDeprecation.h header when the API is added.

Note that, unlike, the old VTK_LEGACY_REMOVE mechanism, the APIs are not deleted. This does interfere with various kinds of deprecations.

  • Changing the return type: Don’t do this. Use a new name for the function.

  • Deprecating macros: Use VTK_LEGACY_REMOVE. New macro APIs should be highly discouraged.

Lifetime of deprecated APIs#

Deprecated APIs should exist for at least one release with the deprecation warning active. This gives consumers of VTK at least one cycle to notice the deprecation and move off of it.

Upon branching for a release, master will soon after have all instances of deprecated symbols removed.

Avoiding warnings within VTK#

VTK is providing the deprecated symbols and as such may still use them in tests or implementations. Since these generate warnings when compiling VTK itself, classes which define deprecated symbols must suppress them.

Sources which continue to use the deprecated macros should add a comment to the top of the source file to hide deprecation warnings in CI.

// Hide VTK_DEPRECATED_IN_X_Y_Z() warnings for this class.
#define VTK_DEPRECATION_LEVEL 0

If one already exists, please add another comment to it so that when deprecated symbols are removed, it shows up in the search.

Deprecation policy#

Ideally, any part of the public API of VTK, installed via its public headers should be deprecated instead of being removed.

When deprecating anything, it is critical to ensure that they keep operating as expected, if not, it would not be a deprecation but a bug.

In that regards, here is the deprecation policy:

  • public structs/defines/enums/functions: must be deprecated

  • public member variables: Should not exist but if they do, must be deprecated

  • public member functions: must be deprecated

  • public virtual member functions: must be deprecated unless in force majeure case, which must be discussed with the community

  • protected members variables: Can just be removed and mentioned in markdown release notes

  • protected member functions: Should be deprecated but removal and mention in markdown can be acceptable in hard cases

  • protected virtual member functions: Can be deprecated but removal and mention in markdown is also ok

Using VTK_DEPRECATION_LEVEL#

When using VTK, the VTK_DEPRECATION_LEVEL macro may be set to a version number. APIs which have been deprecated after this point will not fire (as the API is not deprecated as of the level requested). It should be defined using the VTK_VERSION_CHECK(major, minor, patch) macro.

Note that APIs on the verge of deletion (those deprecated in at least one release) will always raise deprecation warnings.

If not set, its value defaults to the current level of VTK.