Re: [hibernate-dev] Marking API members as incubating
2013/7/11 Hardy Ferentschik > > On 11 Jan 2013, at 12:30 PM, Gunnar Morling wrote: > > > 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. > > would you get that out of the box? > I only know about Eclipse; There you see by default the declared annotations when hovering with the mouse over a method. Of course it's the same with JavaDoc if you have downloaded it. > > The latter also doesn't give me the possibility for tool-based access to > this information. > > Yes in theory, but honestly do you really expect someone is building such > a tool? Maybe if this > @Experimental/@Incubating annotation would be some sort of standard, but > building a tool > to discover incubating features of let's say Hibernate Validator seems > over the top. > I could envision a more generic tool which is configurable with the annotations to watch for. Similar to Eclipse which has a nullability check based on a configurable custom @NonNull annotation. > > > Are there any specific issues you see about using an annotation? > > I am not per se against it. I am just trying to fully understand how it > would look like (aka > retention, etc). For now the only convincing argument for me for such an > annotation would be > the generation of the "Use" javadocs. For that a SOURCE level retention > would be sufficient. > The tooling argument I find not very convincing and is imo only practical > in case of a RUNTIME > retention. > It could be RUNTIME, but I think a user wouldn't check for references to incubating APIs at the runtime of her application but more likely at development/build time. For that purpose CLASS would suffice. Using SOURCE would cause the annotation not to show up in the user's IDE, so I think it should be one of the other two retention levels. > --Hardy ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
On Thu 2013-07-11 14:37, Hardy Ferentschik wrote: > > On 11 Jan 2013, at 12:18 PM, Gunnar Morling wrote: > > > 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. > > Ok. I was replying before reading all thread messages. > What I don't get is how a retention of CLASS works. So it is in the byte > code, but does not have to be retained at runtime. > This means I cannot reflectively determine whether this annotation exists. > What's the point in this case? The only way > to build tooling around this in this case would be to read the actual byte > code. Or am I missing something? > > > 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? > > See above. > > > > Would the aftertaste be gone with using CLASS retention? > > Not unless you explain me how one would actually use such an annotation. Yes CLASS retention requires to read the bytecode or some higher level library that read the Java class metamodel. I am not sure but I suspect that's what IDEs do, they don't load your class in a CL to read the annotation and list of methods. So the CLASS retention would be sufficient for an IDE to expose the information to the user. One concern about annotations is that there is no standard propagation level: you cannot say that a constraint on package is thus placed on all classes in that package. Same for method vs class. You can define such convention but then you need a specific tool understanding these conventions. So annotating a package with @Experimental would not be visible to someone navigating an API in an IDE (with auto-completion for example). to be fair JavaDocs have the same problem. Emmanuel ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
On 11 Jan 2013, at 12:30 PM, Gunnar Morling wrote: > 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. would you get that out of the box? > The latter also doesn't give me the possibility for tool-based access to this > information. Yes in theory, but honestly do you really expect someone is building such a tool? Maybe if this @Experimental/@Incubating annotation would be some sort of standard, but building a tool to discover incubating features of let's say Hibernate Validator seems over the top. > Are there any specific issues you see about using an annotation? I am not per se against it. I am just trying to fully understand how it would look like (aka retention, etc). For now the only convincing argument for me for such an annotation would be the generation of the "Use" javadocs. For that a SOURCE level retention would be sufficient. The tooling argument I find not very convincing and is imo only practical in case of a RUNTIME retention. --Hardy ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
On 11 Jan 2013, at 12:18 PM, Gunnar Morling wrote: > 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. Ok. I was replying before reading all thread messages. What I don't get is how a retention of CLASS works. So it is in the byte code, but does not have to be retained at runtime. This means I cannot reflectively determine whether this annotation exists. What's the point in this case? The only way to build tooling around this in this case would be to read the actual byte code. Or am I missing something? > 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? See above. > Would the aftertaste be gone with using CLASS retention? Not unless you explain me how one would actually use such an annotation. --Hardy ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
2013/7/11 Hardy Ferentschik > > On 10 Jan 2013, at 11:07 PM, Gunnar Morling wrote: > > > 2013/7/10 Steve Ebersole > > > >> 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. > As a user, I personally prefer to get as much context-relevant information and documentation as possible directly from within my IDE instead from other sources of documentation. 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? --Hardy > ___ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev > ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
2013/7/11 Sanne Grinovero > 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? > What is @Experimental here, a JavaDoc tag or an annotation? IMO an annotation is advantageous for the reasons outlined in my initial mail. > > Cheers, > Sanne > > On 11 July 2013 10:11, Hardy Ferentschik wrote: > > > > On 10 Jan 2013, at 11:07 PM, Gunnar Morling > wrote: > > > >> 2013/7/10 Steve Ebersole > >> > >>> 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@lists.jboss.org > > https://lists.jboss.org/mailman/listinfo/hibernate-dev > ___ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev > ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
2013/7/11 Hardy Ferentschik > > On 10 Jan 2013, at 5:48 PM, Gunnar Morling wrote: > > > 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. > > I think that is the easiest. IMO that is sufficient. > > > 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]. > > How out iic the box is that? Looking at our javadocs the class use tab is > not active > in any of our projects. Is that just because we are not using the right > options for the > javadoc plugin or would we need a custom doclet (and styles)? > That's a good question. There is a "Uses" tab at least in the HV docs, but it seems only sparsely populated. I'd need to look into this in more detail. > > > * 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. > > 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? > > * An annotation is more tool friendly, e.g. a user could easily find all > > references to @Incubating in her IDE > > Again, provided the sources are attached. Unless of course we have a > runtime retention. > This is by the way what Gradle uses for its @Incubating annotation. I > think if we go down the > path of using annotations runtime retention might be the better option. > Only this would allow > users to somehow build some tooling around it. The question is whether we > want this annotation > to have a runtime retention. Somehow it has a strange aftertaste, at least > for me. > Would the aftertaste be gone with using CLASS retention? > > or even write an annotation processor > > or a custom CheckStyle rule issuing a build warning when using an > > incubating member > > This would assume the user actually builds our sources. That's not the > case. He uses them as libraries. > > > Such an annotation would have a retention level of SOURCE similar to > other > > documenting annotations such as @Generated. > > See above. > > --Hardy > ___ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev > ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
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 wrote: > > On 10 Jan 2013, at 11:07 PM, Gunnar Morling wrote: > >> 2013/7/10 Steve Ebersole >> >>> 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@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
On 10 Jan 2013, at 11:07 PM, Gunnar Morling wrote: > 2013/7/10 Steve Ebersole > >> 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@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
On 10 Jan 2013, at 6:13 PM, Emmanuel Bernard 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. I don't think that a shared project is required. You could add the annotation to the main source tree. If the retention is source you just have to exclude it from the generated jar. However, as said in my previous email, I am wondering whether to make this really useful for users, the retention would need to be runtime. In this case one would almost have to add the annotation to the project sources, since we would otherwise create a new runtime dependency. --Hardy ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
On 10 Jan 2013, at 5:48 PM, Gunnar Morling wrote: > 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. I think that is the easiest. IMO that is sufficient. > 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]. How out iic the box is that? Looking at our javadocs the class use tab is not active in any of our projects. Is that just because we are not using the right options for the javadoc plugin or would we need a custom doclet (and styles)? > * 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. 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. > * An annotation is more tool friendly, e.g. a user could easily find all > references to @Incubating in her IDE Again, provided the sources are attached. Unless of course we have a runtime retention. This is by the way what Gradle uses for its @Incubating annotation. I think if we go down the path of using annotations runtime retention might be the better option. Only this would allow users to somehow build some tooling around it. The question is whether we want this annotation to have a runtime retention. Somehow it has a strange aftertaste, at least for me. > or even write an annotation processor > or a custom CheckStyle rule issuing a build warning when using an > incubating member This would assume the user actually builds our sources. That's not the case. He uses them as libraries. > Such an annotation would have a retention level of SOURCE similar to other > documenting annotations such as @Generated. See above. --Hardy ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
On Wed 10 Jul 2013 04:07:33 PM CDT, Gunnar Morling wrote: > I sometimes think about a similar approach (in terms of using > annotations) to marking the API/SPI/INTERNAL split. > > > An interesting idea. Would this mean to add annotations to every type? > If so, I'm not sure though how well annotations would "scale" here. > Also e.g. exporting API types in OSGi manifests is centered around > packages. Ideally I'd like to be able to apply it to packages as well. In terms of ORM, for example, it would be nice to annotate the org.hibernate.metamodel package on master and 4.x branches as @Incubating (or whatever annotation we use). I guess it depends on the breadth of the new feature. If its changes/adds are small in number maybe its enough to annotate just the changed/added contracts. You are correct about OSGi manifests being package centric. However, I was getting at something that is a bit more fine-grained in an attempt to further sub-categorize SPI contracts in terms of intended usage. Some SPI contracts are meant simply to expose information to SPI, whereas other SPI contracts define the SPI. In the first case we support the intended usage of those contracts; in the latter case we support certain SPI providers, in some cases application-supplied. Dunno if its useful generally, but I know of one hat I sometimes wear where this would be useful. Of course, we could also support @SPI, @API, @Internal on packages only. Packages without classification would be considered @API, much like we do today with the package-naming approach. ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
2013/7/10 Steve Ebersole > 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 sometimes think about a similar approach (in terms of using > annotations) to marking the API/SPI/INTERNAL split. > An interesting idea. Would this mean to add annotations to every type? If so, I'm not sure though how well annotations would "scale" here. Also e.g. exporting API types in OSGi manifests is centered around packages. > 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 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@lists.jboss.org > >>> https://lists.jboss.org/mailman/listinfo/hibernate-dev > >> ___ > >> hibernate-dev mailing list > >> hibernate-dev@lists.jboss.org > >> https://lists.jboss.org/mailman/listinfo/hibernate-dev > > ___ > > hibernate-dev mailing list > > hibernate-dev@lists.jboss.org > > https://lists.jboss.org/mailman/listinfo/hibernate-dev > > ___ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev > ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
2013/7/10 Sanne Grinovero > 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 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@lists.jboss.org > >> https://lists.jboss.org/mailman/listinfo/hibernate-dev > > ___ > > hibernate-dev mailing list > > hibernate-dev@lists.jboss.org > > https://lists.jboss.org/mailman/listinfo/hibernate-dev > ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
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 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@lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> ___ >> hibernate-dev mailing list >> hibernate-dev@lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev > ___ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
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 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@lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev > ___ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
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@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
Re: [hibernate-dev] Marking API members as incubating
The Gradle team do this exact thing as well. They have been doing that for over a year. You might want to ask them about their experiences. On 07/10/2013 10:48 AM, 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@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev ___ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
[hibernate-dev] Marking API members as incubating
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@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
