How long should we keep deprecated methods?

bitplane · Post by **bitplane** » Mon Feb 14, 2011 3:52 pm

I just removed getMS3DJointNode and getXJointNode which had been sat in the API unused for a few years and was thinking: what amount of time is a reasonable length to keep deprecated methods before they are removed from the API?

I was thinking two, maybe three major releases, with a warning in the docs saying when they were deprecated and/or when they will be removed.

Any thoughts, objections or other ideas? How do other APIs deal with this?

Radikalizm · Post by **Radikalizm** » Mon Feb 14, 2011 4:02 pm

I don't know how other libraries handle this, but three major releases seems a bit long to me

I always interpret deprecated functions as 'don't expect this function to be available in the next release', and maybe it's not a bad idea to keep deprecated functions for just one major release so people don't integrate these too deeply in their code

hybrid · Post by **hybrid** » Mon Feb 14, 2011 4:29 pm

Yeah, I'd also take one or two major releases as typical. However, some projects keep deprecated functions for ages...

Nadro · Post by **Nadro** » Mon Feb 14, 2011 5:10 pm

In my opinion, if in current major release we have signed some function as a deprecated in next major release this function should be removed.

Brainsaw · Post by **Brainsaw** » Tue Feb 15, 2011 7:04 am

Imho it would be OK to remove such methods in the next major version (one version where it's marked as deprecated, next version it's gone). I guess this helps to keep the interface small.

REDDemon · Post by **REDDemon** » Tue Feb 15, 2011 8:25 am

sure remove early unused code and make irrlicht more modern in the fastest possible way

. what is deprecated now can be removed from 1.8 and what is marked as deprecated in 1.8 will be removed in 1.9

agamemnus · Post by **agamemnus** » Tue Feb 15, 2011 8:26 am

Doesn't matter to me, as long as the API and docs clearly state it will be deprecated... in huge bold capitalized letters nobody can miss. (instead of a tiny footnote for example...)

Also, what would be great is that along with the note, we can clearly see what methods/function(s) it is replaced by.

bitplane · Post by **bitplane** » Tue Feb 15, 2011 1:57 pm

Okay, I'll go through the deprecated methods in trunk (1.

and mark them for removal in 1.9. The \deprecated tag doesn't appear to be showing up in the doxygen docs, I guess this needs fixing.

hybrid · Post by **hybrid** » Tue Feb 15, 2011 5:03 pm

There's a \deprecated tag for Doxygen, which we already used for e.g. the bine methods you just removed.

bitplane · Post by **bitplane** » Tue Feb 15, 2011 5:40 pm

Oh, you're right, I see them now.

agamemnus · Post by **agamemnus** » Tue Feb 15, 2011 7:34 pm

Just as an extra: if possible, I would make several improvements to the style. All the functions just kind of meld together right now.

*First, I would separate each item with a line break and a space. (between the "returns" section and the parameters section of a next function)

* Second, I would put create a heading text for each item before its parameters section. IE: "createImage" in (bold?) bigger text, as a heading, before its parameters box.

* I would put an additional "(deprecated)" tag for the heading if it is deprecated... I realize that a lot of functions are overloaded, so I am not sure how to easily modify this to handle overloaded functions.

* More info for deprecated section. For example, for one of the "createImage"s, it is stated that we should "Create an empty image and use copyTo()", but there is no link or other explanation on how we should actually create an empty image.

hybrid · Post by **hybrid** » Wed Feb 16, 2011 1:19 pm

You can create your own doxygen style as you want and re-run the API creation process locally.

bitplane · Post by **bitplane** » Wed Feb 16, 2011 1:37 pm

Or even better, post the changes to the patch tracker

pippy3 · Post by **pippy3** » Thu Feb 17, 2011 1:46 am

Am I evil for thinking as soon as its deprecated, just remove it?

A quick google of the error after upgrading irrlicht versions will likely point to a forum post of someone with the same problem and solution.

Brainsaw · Post by **Brainsaw** » Thu Feb 17, 2011 6:48 am

IIRC "deprecated" is used to give developers some time to modify their code to use non-deprecated methods, so I thinks it's a good idea to keep those functions in for one major version. I don't know if the current C++ compilers support a "deprecated" warning that points you to deprecated methods you use - Java does (about the only thing I really like in Java

).