My view is that they are useful. We publish docs for all release versions (the version number is part of the path in the URL). We don't provide an easy way to navigate to these versioned docs though. If you know what the URL looks like, you can hand edit the URL.
I think we have the since annotations going back a long time and some people may rely on them. It can be really helpful for Pekko developers investigating issues if the since details are in the code. I think it is also healthy for us to discuss whether we intend to backport changes when we are reviewing PRs. In the rare occurrence where we decide to backport after the original merge then we might also need to modify the since tag in the main branch. I still think this is pretty easy to do if it ever needs to be done. On 2024/11/27 15:42:41 Arnout Engelen wrote: > Hello, > > (prompted by https://github.com/apache/pekko-http/pull/630) > > We currently add "@since x.y.z" annotations to the Java/Scaladoc when > we add new classes, variables or functions to public APIs. > > I'm not sure they're very useful: I rarely look at them, as I usually > use the documentation from my IDE. It's quite rare that I find > something in the online docs that I'm missing locally - and even in > such a case the added value of the annotation seems limited. > > Having these annotations is some work: > * We have to ask contributors to add them if they don't do so by themselves > * If a release is made, any annotations in remaining open PRs need to be > updated > * If a PR is merged that requires a major/minor version bump, any > annotations in open PRs that only needed minor/patch bumps need to be > updated > * If you intend your change to be backported things can get more > complicated as well > > I'd be interested in hearing your thoughts on maybe no longer requiring them. > > > Kind regards, > > -- > Arnout Engelen > ASF Security Response > Apache Pekko PMC member, ASF Member > NixOS Committer > Independent Open Source consultant > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@pekko.apache.org > For additional commands, e-mail: dev-h...@pekko.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@pekko.apache.org For additional commands, e-mail: dev-h...@pekko.apache.org
