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/... _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

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/... > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

http://www.gradle.org/docs/current/userguide/feature_lifecycle.html

I sometimes think about a similar approach (in terms of using annotations) to marking the API/SPI/INTERNAL split.

On 07/10/2013 11:23 AM, Sanne Grinovero wrote: > 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.. > > On 10 July 2013 17:13, Emmanuel Bernard <emmanuel(a)hibernate.org&gt; 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/... >>> _______________________________________________ >>> hibernate-dev mailing list >>> hibernate-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> _______________________________________________ >> hibernate-dev mailing list >> hibernate-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

2013/7/10 Steve Ebersole <steve(a)hibernate.org&gt; > http://www.gradle.org/docs/current/userguide/feature_lifecycle.html Thanks for the link. I like their approach of explicitly documenting this kind of thing.

Indeed in my previous comment about bundling it in a common jar I was assuming the retention would have been at source level. Hardy suggested we could keep it even at runtime.. indeed that could open the path for several kinds of diagnostics and reporting. I guess there is no downside? I don't expect these to take more than a couple of bytes in the class definitions. +1 to just include it in the source tree, but in that case I'm not sure I'm understanding the additional value over the current @Experimental?

Cheers, Sanne On 11 July 2013 10:11, Hardy Ferentschik <hardy(a)hibernate.org&gt; wrote: > > On 10 Jan 2013, at 11:07 PM, Gunnar Morling <gunnar(a)hibernate.org&gt; wrote: > >> 2013/7/10 Steve Ebersole <steve(a)hibernate.org&gt; >> >>> http://www.gradle.org/docs/current/userguide/feature_lifecycle.html >> >> >> Thanks for the link. I like their approach of explicitly documenting this >> kind of thing. > > I think we might have to differentiate here. I also like the clear documentation of Gradle, > but having an @Incubating annotation is imo not a requirement for that. We could create > something similar on our wiki or include into our online docs. It could mention Experimental > javadoc in our case. > > --Hardy > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

I think hovering over a method I want to use in my IDE and seeing it is annotated with @Incubating gives me that information much faster than going to a wiki or online docs.

The latter also doesn't give me the possibility for tool-based access to this information.

Are there any specific issues you see about using an annotation?

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..

On 10 July 2013 17:13, Emmanuel Bernard <emmanuel(a)hibernate.org&gt; 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/... >> _______________________________________________ >> hibernate-dev mailing list >> hibernate-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev

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.

Here is the thing, we need to also need to start talking retention setting of the annotation. I think you were suggesting source retention. This means that the annotation is only in the source. That means the IDE needs to be linked to the source. I would assume that often developers will setup their IDEs to download sources automatically, but it is not a given. Yes, you're right. See my response to Sanne's previous message: > 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.

For the reasons you describe, SOURCE indeed is wrong, but I think CLASS would suffice (that's also what Guava's @Beta uses) which puts it into the class files of types using it. Or is there a need to access the annotation reflectively at runtime?

Would the aftertaste be gone with using CLASS retention?