The future of VTK_LEGACY_REMOVE

[ben.boeckel (Ben Boeckel (Kitware))]

[ I had this as a draft and never actually published it. Sorry for the delay in this information. ]

Is to be removed itself .

Instead, there will now be VTK_DEPRECATED_IN_X_Y_Z where X, Y, and Z form the version number when the API was deprecated. I’ve gone and done this for the APIs currently deprecated in master.

Old method:

#include "vtkLegacy.h"

VTK_LEGACY(void someOldMethod());

// in the source

#ifndef VTK_LEGACY_REMOVE
void someOldMethod() {
  VTK_LEGACY_BODY(someOldMethod, "VTK next.version")
}
#endif

It now looks like:

#include "vtkDeprecation.h"

VTK_DEPRECATED_IN_9_0_0("a reason for the deprecation and/or guidance on porting")
  void someOldMethod();

// in the source

void someOldMethod() {
  // This might warrant a new macro, but maybe not.
  VTK_LEGACY_BODY(someOldMethod, "VTK next.version")
}

Benefits over the old way:

• The code doesn’t disappear overnight. Once 9.1.0 is branched, we can go and clean out the 9.0.0 APIs (as they’ll still be in 9.1.0 so they can warn users of these APIs)

• Warnings always show up and code continues working in the meantime

• Warnings can be turned off by doing #define VTK_DEPRECATION_LEVEL VTK_VERSION_CHECK(9, 1, 0). This warns about APIs deprecated in 9.0.0, but keeps 9.1.0-deprecations silent.
  What won’t be possible with the new way that was with the old:

• changing return values of methods

  • Solution: Deprecate the current name and use a new name for the method. There’s one instance which is still on VTK_LEGACY_REMOVE today.

• macros

  • Solution: We could deprecate then via _Pragma, but that’s not as nice. Let’s just stop having macro APIs . These can continue to use VTK_LEGACY_REMOVE in the meantime. These aren’t too prevalent, so keeping them around for a while also shouldn’t be too bad.

With this will come a versioning scheme to help support this. Releases will be the same, but the master branch will use a date for the patch level. As an example:

release -> 9.0.0 -> 9.0.1 -> etc. (all tagged), 9.0.20201030 at branch point -> 9.1.0.rc1 (a tag, should be right after the date branch, so that’s “unobservable”)
master -> 9.0.20200511 today -> 9.0.20200512 tomorrow -> 9.1.20201031 once 9.1 branches (never tagged)

This means that if you’re tracking master and need an API added on July 4th, you can do find_package(VTK 9.0.20200704) and you’re set; 9.1 will satisfy as will an August-based build.

Future improvements:

• wrappers recognize these macros and add @deprecated annotations (Java) or decorators (Python) to the wrapped function (docstrings can also get modified)
• ParaView gets its own VTK_DEPRECATED macro stack based on its version number (no more free ride here )
• We could actually hide these by having them magic away the methods using some SFINAE magic. VTK should always build them however; users just lose access to the declaration based on their minimum VTK request. There are definitely issues with this though (e.g., making a virtual disappear affects ABI)

–Ben

[seanm (Sean McBride)]

And some automated process increments VTK_BUILD_VERSION every day? At what time? I’d guess 21:00, the same time a new “night” starts on cdash?

Sean

[ben.boeckel (Ben Boeckel (Kitware))]

It’s bumped UTC midnight. So 7 or 8 Eastern depending on the time of year.

[seanm (Sean McBride)]

So if one wants to deprecate an API in today’s master, how does one know whether to use VTK_DEPRECATED_IN_9_0_1, VTK_DEPRECATED_IN_9_1_0, or VTK_DEPRECATED_IN_10_0_0? i.e. how does one know what version master will next be released as? Will it be 9.0.1, 9.1, or 10.0? One might think to look at vtkVersionMacros.h, but that doesn’t help because master still describes itself as 9.0.x.

There’s also this:

// VTK defaults to deprecation of its current version.
#include "vtkVersionMacros.h"
#define VTK_DEPRECATION_LEVEL VTK_VERSION_NUMBER

Which is confusing to me at least. “its current version” means master’s version? or the version of the current public release?

Lastly, I’m getting this new warning:

vtkOpenGLRenderWindow.h:201:7: Declaration is marked with '\deprecated' command but does not have a deprecation attribute

from this:

  /**
   * @deprecated in VTK 9.1
   */
  VTK_DEPRECATED_IN_9_1_0("Removed in 9.1")
  unsigned int GetBackLeftBuffer();

VTK_DEPRECATED_IN_9_1_0 doesn’t actually emit a deprecation attribute because master calls itself 9.0.x despite master actually being 9.1, I guess.

Thanks,

Sean

[ben.boeckel (Ben Boeckel (Kitware))]

@seanm

So if one wants to deprecate an API in today’s master, how does one know whether to use VTK_DEPRECATED_IN_9_0_1, VTK_DEPRECATED_IN_9_1_0, or VTK_DEPRECATED_IN_10_0_0? i

Use 9_1_0 (or generally, the latest version of the macro). If we decide the next version is 10.0, we have lots of other things up update as well anyways. 9.0.1 doesn’t use this mechanism so you can’t really use it. You couldn’t anyways because 9.0.20200601 did not have it deprecated.

Really, this means that deprecations should not be eligible for patch versions. We should not have allowed deprecating IsDrawable for 9.0.x once it missed 9.0.0.

@seanm

VTK_DEPRECATED_IN_9_1_0 doesn’t actually emit a deprecation attribute because master calls itself 9.0.x despite master actually being 9.1, I guess.

And it wouldn’t if you had a lower VTK_DEPRECATION_LEVEL either that made it not warn because you’re targeting a version that doesn’t have it deprecate it. I’d ignore it.