Sounds like we're relitigating the basics of how @Deprecated, forRemoval,
since, and javadoc @link all intersect to make deprecation less painful ;)
So:
1. Built-in java.lang.Deprecated: required
2. Can use since and forRemoval if you have that info handy and think it'd be
useful (would make it a lot easier to grep for things to pull before a major)
3. If it's being replaced by something, you should {@link #} the javadoc for
it so people know where to bounce over to
I've been leaning pretty heavily on the functionality of point 3 for
documenting cross-module implicit dependencies as I come across them lately so
that one resonates with me.
On Tue, Oct 10, 2023, at 4:38 AM, Miklosovic, Stefan wrote:
> OK.
>
> Let's go with in-built java.lang.Deprecated annotation. If somebody wants to
> document that in more detail, there are Javadocs as mentioned. Let's just
> stick with the standard stuff.
>
> I will try to implement this for 5.0 (versions since it was deprecated) with
> my take on what should be removed (forRemoval = true) but that should be
> definitely cross-checked on review as Mick mentioned.
>
> ________________________________________
> From: Mick Semb Wever <m...@apache.org>
> Sent: Monday, October 9, 2023 10:55
> To: dev@cassandra.apache.org
> Subject: Re: [DISCUSS] putting versions into Deprecated annotations
>
> NetApp Security WARNING: This is an external email. Do not click links or
> open attachments unless you recognize the sender and know the content is safe.
>
>
>
> Tangential question to this is if everything we deprecated is eligible for
> removal? In other words, are there any cases when forRemoval would be false?
> Could you elaborate on that and give such examples or do you all think that
> everything which is deprecated will be eventually removed?
>
>
> Removal cannot be default. This came up in the subtickets of CASSANDRA-18306.
>
> I suggest that adding " forRemoval = true" and the later actual removal of
> the code both require broader consensus. I'm open to that being on the
> ticket or needing a thread on the ML. Small stuff, common sense says on the
> ticket is enough, but a few folk have already stated that deprecated code
> that has minimal maintenance overhead should not be removed.
>
