What is the purpose of enforcing the use of the @since tag?

[victornoel]

The @since tag is enforced by qulice to be used on public elements of a Java API.

I wonder what is the need for it? What does it provide?

We removed in the past the need for the @author tag because it was already covered by version control. The @since tag does not seem to provide anything more than what version control is providing.

But maybe I am missing something. Is there some rationale for it?

If there are none, I propose to remove this rule from qulice.

@yegor256 @krzyk

[0crat]

@krzyk/z please, pay attention to this issue

[0crat]

@victornoel/z this project will fix the problem faster if you donate a few dollars to it; just click here and pay via Stripe, it's very fast, convenient and appreciated; thanks a lot!

[victornoel]

@krzyk any opinion on this?

[victornoel]

@krzyk ping

[llorllale]

@victornoel personally I like this system:

@since should have the value:

• 1.0.0 while we're still pre-1.0
• 1.x.0 for the next feature release
• 1.0.y for the next bug fix

[victornoel]

@llorllale this is a good enough system (even though I'm not clear how I can be able to know, when introducing a class, if the next release is going to be a feature one or a bug fix one), but it does not answer the fundamental question IMHO: what purpose does it have to specify this @since tag? Who uses it? Why?

[llorllale]

@victornoel

the fundamental question IMHO: what purpose does it have to specify this @SInCE tag? Who uses it? Why?

The only practical utility I find is when you have to determine the minimum compatible version of a library that is referenced by several others (dependency hell). This seldom happens based on my experience

[krzyk]

@victornoel @llorllale I think @since tag is usefull only in case of libraries like cactoos, so it can be enforced at the PR review level.
I would vote to drop that requirement enforcement in qulice, as I assume most projects are not libraries.

@yegor256 Are you OK with dropping @since tag from required tags in qulice?

[llorllale]

@krzyk I could go either way with the removal of @since, but I didn't understand what you said:

usefull only in case of libraries like cactoos, so it can be enforced at the PR review level

What do you mean?

[krzyk]

@llorllale I mean if given library wants to enforce @since tag then it can be enforced by a review of a PR (by a real person) instead by qulice.

[llorllale]

@krzyk qulice should support custom extensions (in addition to the checks already built in) so that projects that want to enforce @since don't have to manually check this

[yegor256]

@krzyk well, I find this tag useful. It indicates the minimum version where this feature is available. I would leave it in the list of required tags.

[victornoel]

@yegor256 what you say is already provided by git, why do we need to have it in the code itself? It's trying to do manually (and often badly because it requires a lot of effort to have correct information, just look at cactoos codebase, it's a mess, the since tags are useless in there) what a versioning system does without fail.

Also, I just don't get why people wants to know that information: usually, when you want to have a method from a lib, you just take the last version and you know you will have it, nobody is going to think "I need this new method, I will take this old version of cactoos full of bugs that were corrected in newer version".

[yegor256]

@victornoel these @since tags are useful for Javadoc generators. They help people understand what's going on without going to git. We'll keep this.