If we want to use some description (of type String), we would need to introduce
a brand new annotation instead of java.lang.Deprecated as that one does not
have it.
I am in favor of custom annotation instead of using Javadocs for this kind of
technical documentation. An annotation seems to be more succinct, even it is a
custom one, rather that using comments for it.
On the other hand, I am not sure how we ensure that developers use this custom
annotation instead of the in-built one. java.lang package is not a package to
be imported so we can not have a checkstyle rule for it.
________________________________________
From: Francisco Guerrero <fran...@apache.org>
Sent: Saturday, October 7, 2023 0:54
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.
> Might be nice to support a 3rd param that's a String for the reason it's
> deprecated.
Javadocs offers this natively
/**
* @deprecated Use instance method {@link #newMethod(Param1, Param2...)}
instead.
*/
@Deprecated
So we could leverage javadocs for this purpose
On 2023/10/06 11:49:52 Josh McKenzie wrote:
> Might be nice to support a 3rd param that's a String for the reason it's
> deprecated. i.e. "Replaced by X", "Unmaintained", "Obsolete", "See
> CASSANDRA-NNNNN", link to a dev ML thread on pony mail, etc. That way if
> someone comes across it in the codebase they have some context to follow up
> on if it's the shape of a thing they need w/out having to go full-bore w/git
> blame and JQL.
>
> On Fri, Oct 6, 2023, at 4:43 AM, Miklosovic, Stefan wrote:
> > Hi list,
> >
> > I have a ticket to discuss (1).
> >
> > When we deprecate APIs / methods etc, what I want to suggest is that we
> > might start to explicitly add the version when that happened. For example,
> > if you deprecated something which goes to 5.0, would you be so nice to do
> > this?
> >
> > @Deprecated(since = "5.0")
> >
> > Similarly, that annotation offers one more field - forRemoval, so using it
> > like this:
> >
> > @Deprecated(since = "5.0", forRemoval = true)
> >
> > means that this is eligible to be deleted in Cassandra 6.0.
> >
> > With this information, it is way more comfortable to just "grep" where we
> > are at when it comes to deprecations eligible to be deleted in the next
> > version. Currently, we basically have to go one by one and figure out if it
> > is not old enough to remove. I believe this would bring more transparency
> > into what is planned to be removed and when as well it will be clearly
> > visible what should be removed in the next version and it is not.
> >
> > 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?
> >
> > (1) https://issues.apache.org/jira/browse/CASSANDRA-18912
> >
> > Thanks and regards
>
