Hello everyone,
I've discussed with Stefan some steps we can take to improve the final solution, so the final version might look like this: /** @deprecated See CASSANDRA-6504 */ @Deprecated(since = "2.1") public Integer concurrent_replicates = null; The issue number will be taken from the git blame comment. I doubt I can generate and/or create a meaningful comment for every deprecation annotation, but providing a link to the issue that was retrieved from the git blame is not too big a problem. This also improves the visibility. In addition, we can add two checkstyle rules [1] [2] to ensure that any future deprecations will have a "since" element and a JavaDoc comment. WDYT? [1] https://checkstyle.sourceforge.io/apidocs/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheck.html [2] https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/checks/coding/MatchXpathCheck.html On Tue, 10 Oct 2023 at 14:50, Josh McKenzie <jmcken...@apache.org> wrote: > > Sounds like we're relitigating the basics of how @Deprecated, forRemoval, > since, and javadoc @link all intersect to make deprecation less painful ;) > > So: > > Built-in java.lang.Deprecated: required > 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) > 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. > >
