Do we know if the external user APIs are consistently marked with @since tags? If only some of these APIs have @since tags then they don't have much value.
If we're going to keep these tags then we should keep them up-to-date and have them consistently applied to all of our external user APIs. We should then add it to our DOD and code style guidelines. If the DOD and guidelines don't specify this then as developers add new classes and methods, we run the risk of not consistently having them in place or in how they are used. For example, if I add a new class to the external user API, should I mark all public methods with @since tags or just the class and what about protected methods? -Kirk On Tue, Apr 26, 2016 at 4:23 PM, Dan Smith <[email protected]> wrote: > I think they may be helpful in the public API - to be able to tell if you > are using a feature that has been around for a while, or to realize what > version you need to upgrade to in order to get a feature. > > -Dan > > On Tue, Apr 26, 2016 at 4:12 PM, Udo Kohlmeyer <[email protected]> > wrote: > > > Just for my own curiosity... why do we need the @since tag? > > What benefit does it provide the product/code? > > > > --Udo > > > > > > On 27/04/2016 7:43 am, Dan Smith wrote: > > > >> It sounds like more people are in favor of Geode 1.0.0 and GemFire > x.y.z, > >> so I created bug GEODE-1316 to implement this change. > >> > >> -Dan > >> > >> On Mon, Apr 25, 2016 at 6:36 PM, Udo Kohlmeyer <[email protected]> > >> wrote: > >> > >> I must be honest that I've never been a supporter of the @since tag. > Imo, > >>> release notes and features should be the paper trail that we provide. > >>> Also, > >>> how would we handle a scenario where a class is denoted with @since > 6.5.x > >>> and all internals of that class are completely new and replaced with > >>> 8.2.x > >>> or even 9.0 (or 1.0 Geode) code? > >>> > >>> I think that @since tags become like comments, without somebody > changing > >>> things, they just become stale and stagnant. I cannot think of many > open > >>> source projects that use @since tags. > >>> > >>> But if we must have them in the code base then I prefer to have them > as a > >>> Geode x.y.z > >>> > >>> > >>> On 26/04/2016 9:56 am, Darrel Schneider wrote: > >>> > >>> +1 for having on explicit GemFire and Geode > >>>> > >>>> > >>>> On Mon, Apr 25, 2016 at 4:43 PM, Kenneth Howe <[email protected]> > wrote: > >>>> > >>>> +1 to “gemFire x.y.z” > >>>> > >>>>> Adding the GemFire makes it obvious where the feature came from, no > >>>>> inference > >>>>> required as would happen if we left just a version number for old > >>>>> @since > >>>>> annotations. > >>>>> > >>>>> Ken > >>>>> > >>>>> On Apr 25, 2016, at 4:39 PM, Kirk Lund <[email protected]> wrote: > >>>>> > >>>>>> +1 for @since Geode 1.0.0 > >>>>>> > >>>>>> If we keep the pre-existing @since tags, then I'd prefer to add > >>>>>> "GemFire" > >>>>>> to them for better clarity. Thus, @since 4.0.0 would be changed to > >>>>>> @since > >>>>>> GemFire 4.0.0. Just my preference. > >>>>>> > >>>>>> -Kirk > >>>>>> > >>>>>> > >>>>>> On Mon, Apr 25, 2016 at 4:32 PM, Sai Boorlagadda < > >>>>>> > >>>>>> [email protected]> > >>>>> > >>>>> wrote: > >>>>>> > >>>>>> +1 for Geode 1.0.0 > >>>>>> > >>>>>>> And we can leave current @since tags as-is with out "GemFire" to > >>>>>>> denote > >>>>>>> predate Geode. > >>>>>>> So if you see "Geode x.y.z" => added in Geode > >>>>>>> or "x.y.z" => Predate to Geode > >>>>>>> (i.e.,) > >>>>>>> GemFire. > >>>>>>> > >>>>>>> > >>>>>>> On Fri, Apr 22, 2016 at 3:37 PM, John Blum <[email protected]> > wrote: > >>>>>>> > >>>>>>> +1 for @since Geode 1.0.0. > >>>>>>> > >>>>>>>> @since GemFire x.y.z is probably not all that useful from a Geode > >>>>>>>> perspective, but maybe important in GemFire source, particularly > for > >>>>>>>> features that maybe specific to GemFire, or predate Geode. > >>>>>>>> > >>>>>>>> On Fri, Apr 22, 2016 at 3:11 PM, Dan Smith < > >>>>>>>> [email protected] > >>>>>>>> wrote: > >>>>>>>> > >>>>>>>> Hi, > >>>>>>>> > >>>>>>>>> We have a lot of @since tags in our javadocs with old gemfire > >>>>>>>>> versions. I think we are going to keep them in there, we should > >>>>>>>>> maybe > >>>>>>>>> do a sweep and add gemfire to the version: > >>>>>>>>> > >>>>>>>>> Eg > >>>>>>>>> @since GemFire 5.5 > >>>>>>>>> > >>>>>>>>> For geode @since tags, we can start from 1.0: > >>>>>>>>> @since 1.0 > >>>>>>>>> > >>>>>>>>> Or maybe it would be better to be explicit? > >>>>>>>>> @since Geode 1.0 > >>>>>>>>> > >>>>>>>>> What do you guys think? > >>>>>>>>> -Dan > >>>>>>>>> > >>>>>>>>> > >>>>>>>>> -- > >>>>>>>> -John > >>>>>>>> 503-504-8657 > >>>>>>>> john.blum10101 (skype) > >>>>>>>> > >>>>>>>> > >>>>>>>> -- > >>>>>>> Sai Boorlagadda > >>>>>>> > >>>>>>> > >>>>>>> > > >
