I think it's useful, otherwise users have to access the source code with git blames. 何品
PJ Fanning <fannin...@apache.org> 于2024年12月4日周三 21:06写道： > 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 > >
