[hibernate-dev] Marking API members as incubating

[Gunnar Morling]

2013/7/10 Sanne Grinovero <sanne at hibernate.org>

> To share the annotation?
> We where contemplating a shared jar anyway to maintain the checkstyle
> rules. I guess this could also contain some other shared stuff, like
> the CSS extensions to the javadoc, etc..
>

But isn't there a difference between shared resources such as CS rules
required at build time (of our projects) and the annotation which would
have to be visible to the user? I.e. does it make sense to have these
things in one JAR? Btw. I got the retention wrong in my first message, it
should be CLASS so a user can see whether its present on any API members.

Personally I wouldn't mind if there was a specific annotation in those
projects making use of the concept. I don't think its itself worth a shared
JAR and should there ever be such one later on, the specific annotations
could be abandoned in favor of a shared one. As such an annotation would
not be intended to be imported by clients this shouldn't be a problematic
change for users. We also might put @MetaIncubating to a project specific
annotation ;)

Other candidates for a shared annotation JAR might be
@TestForIssue/@IssueKey used in tests or something like @ThreadSafe,
@GuardedBy etc. as suggested in Java Concurrency in Practice to document
thread-safety/locking behaviors.

--Gunnar



> On 10 July 2013 17:13, Emmanuel Bernard <emmanuel at hibernate.org> wrote:
> > I remember a few discussion where something like that has been
> > contemplated. One thing that made us not do it AFAIR is that we would
> > need some kind of shared project to host this across ORM, OGM, SEARCH
> > etc. In the past we have deemed it not worth it.
> >
> > Emmanuel
> >
> > On Wed 2013-07-10 17:48, Gunnar Morling wrote:
> >> Hi,
> >>
> >> Hardy and I have been musing about how to mark new API members (methods,
> >> classes etc.) which are still incubating or experimental.
> >>
> >> Of course we have Alpha, Beta releases etc. but there can be cases
> where it
> >> makes sense to ship new functionality with a final release and still
> leave
> >> the door open for refinements in the next release based on user
> feedback.
> >>
> >> So basically we're looking for a way to inform the user and say "it's
> ok to
> >> use this API, but be prepared to changes in the future". One way to do
> this
> >> is documentation, i.e. prose or a custom JavaDoc tag such as
> @experimental.
> >> This has been done in HSEARCH before.
> >>
> >> Alternatively a Java 5 annotation could be used which I'd personally
> find
> >> advantageous for the following reasons:
> >>
> >>  * With an annotation, the generated JavaDoc gives you a list with all
> >> incubating members out of the box, see e.g. the Guava docs for an
> example
> >> [1].
> >>
> >> * For an annotation we can provide proper documentation in form of
> JavaDoc,
> >> i.e. the user of the API can inspect the docs of @Incubating from within
> >> the IDE and learn about the rules behind it. For a tag, a user would
> only
> >> see the specific comment of a given instance.
> >>
> >> * An annotation is more tool friendly, e.g. a user could easily find all
> >> references to @Incubating in her IDE or even write an annotation
> processor
> >> or a custom CheckStyle rule issuing a build warning when using an
> >> incubating member
> >>
> >> Such an annotation would have a retention level of SOURCE similar to
> other
> >> documenting annotations such as @Generated.
> >>
> >> Any thoughts?
> >>
> >> --Gunnar
> >>
> >> [1]
> >>
> http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/annotations/class-use/Beta.html
> >> _______________________________________________
> >> hibernate-dev mailing list
> >> hibernate-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev
> > _______________________________________________
> > hibernate-dev mailing list
> > hibernate-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/hibernate-dev
>