Re: [RELEASE PROCESS] Stability versus usability
Hi Jörg; I've amended the idea based on feedback to *internal* package and @internal annotation (for pragmatic reasons: a good rule is one which is easy to follow and enforce). The naming convention or the annotation would allow clear but also explicit boundary; documentation is necessary but not sufficient IMHO. It should be possible to determine automatically whether public code unintentionally exposes or uses an @internal class by transitivity. I agree that packaging should be the preferred way but sometimes, it may be too hard/long/costly to refactor the project; sprinkling annotations would not be ideal but would still allow control over the API stability. Cheers, Henrib PS: We might need @experimental or @beta for APIs intended for public use but not stable enough to make a hard cast-in-stone stable contract. -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4164209.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
Henri, I would love to see this as a Commons recommendation on the Wiki. As Stefan mentioned, in Compress we have @experimental annons (I actually added them). I like the idea to make up a public, rarely to break interface api and some not so public sometimes to break implementation. Maybe we should even consider to create an interface jar and an implementation jar of different versions. On the other hand this makes things complex - but anyway Cheers Christian On Sun, Dec 4, 2011 at 11:41 AM, henrib hen...@apache.org wrote: Keeping track as it evolves based on feedback; Goal is to allow easy definition, usage and check of stable APIs. An annotation and a package naming convention allow the project developer to clearly state when a class/method/field is not part of the stable contract despite a public/protected declaration but only of the internal part of the project. @internal annotated class/method or *internal* package mean use this at your own maintenance cost; those are not part of the public API. They can be used and extended but are subject to change between versions without @deprecated annotations. Those annotations and conventions should allow feeding a clirr report with the proper information to allow detection of unintended API breakage and may even allow creating IDE plugins to warn about usage. -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156552.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org -- http://www.grobmeier.de https://www.timeandbill.de - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
+1 Christian this is a nice idea - maybe RetentionPolicy.SOURCE annotations? (so we don't have to bring the dependency in each component for runtime...) Simo http://people.apache.org/~simonetripodi/ http://simonetripodi.livejournal.com/ http://twitter.com/simonetripodi http://www.99soft.org/ On Mon, Dec 5, 2011 at 4:21 PM, Christian Grobmeier grobme...@gmail.com wrote: Henri, I would love to see this as a Commons recommendation on the Wiki. As Stefan mentioned, in Compress we have @experimental annons (I actually added them). I like the idea to make up a public, rarely to break interface api and some not so public sometimes to break implementation. Maybe we should even consider to create an interface jar and an implementation jar of different versions. On the other hand this makes things complex - but anyway Cheers Christian On Sun, Dec 4, 2011 at 11:41 AM, henrib hen...@apache.org wrote: Keeping track as it evolves based on feedback; Goal is to allow easy definition, usage and check of stable APIs. An annotation and a package naming convention allow the project developer to clearly state when a class/method/field is not part of the stable contract despite a public/protected declaration but only of the internal part of the project. @internal annotated class/method or *internal* package mean use this at your own maintenance cost; those are not part of the public API. They can be used and extended but are subject to change between versions without @deprecated annotations. Those annotations and conventions should allow feeding a clirr report with the proper information to allow detection of unintended API breakage and may even allow creating IDE plugins to warn about usage. -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156552.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org -- http://www.grobmeier.de https://www.timeandbill.de - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
Personally, I do not like annotations to describe the stability of an API. If it's public I can use it. The next release is binary and/or source compatible, just document how to migrate. No one is forcing me to upgrade. If I upgrade, I am using a new pile of code and I must deal with that. Using .internal packages is an interesting way to go. But I do like documentation of some kind for things like immutability and thread-safety. We've started going down the path of what I call extreme versioning when we create new packages for new incompatible releases. Right now, binary incompatible - new package (I'm even going to include Maven artifact ID noise here). But what about a change in behavior that is not compatible? Should that not lead to a new package? Commons is a 'special' project because it includes so many components. It would be nice if all components played by the same rules. Strictly speaking, I think we are bound to do so. Gary On Mon, Dec 5, 2011 at 10:21 AM, Christian Grobmeier grobme...@gmail.comwrote: Henri, I would love to see this as a Commons recommendation on the Wiki. As Stefan mentioned, in Compress we have @experimental annons (I actually added them). I like the idea to make up a public, rarely to break interface api and some not so public sometimes to break implementation. Maybe we should even consider to create an interface jar and an implementation jar of different versions. On the other hand this makes things complex - but anyway Cheers Christian On Sun, Dec 4, 2011 at 11:41 AM, henrib hen...@apache.org wrote: Keeping track as it evolves based on feedback; Goal is to allow easy definition, usage and check of stable APIs. An annotation and a package naming convention allow the project developer to clearly state when a class/method/field is not part of the stable contract despite a public/protected declaration but only of the internal part of the project. @internal annotated class/method or *internal* package mean use this at your own maintenance cost; those are not part of the public API. They can be used and extended but are subject to change between versions without @deprecated annotations. Those annotations and conventions should allow feeding a clirr report with the proper information to allow detection of unintended API breakage and may even allow creating IDE plugins to warn about usage. -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156552.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org -- http://www.grobmeier.de https://www.timeandbill.de - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org -- E-Mail: garydgreg...@gmail.com | ggreg...@apache.org JUnit in Action, 2nd Ed: http://goog_1249600977http://bit.ly/ECvg0 Spring Batch in Action: http://s.apache.org/HOqhttp://bit.ly/bqpbCK Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
Re: [RELEASE PROCESS] Stability versus usability
Hi Gary! On Mon, Dec 5, 2011 at 4:42 PM, Gary Gregory garydgreg...@gmail.com wrote: Personally, I do not like annotations to describe the stability of an API. If it's public I can use it. The next release is binary and/or source compatible, just document how to migrate. No one is forcing me to upgrade. If I upgrade, I am using a new pile of code and I must deal with that. Using .internal packages is an interesting way to go. interesting stuff as well - I learnt a trick from Google Guice team that developed internal stuff only[1] and then obfuscate[2] them in the way most ides won't recognize for code completion, so users cannot rely on internal APIs :P I personally think that is a valid approach, just my 0.02 cents, -Simo [1] http://s.apache.org/dt7 [2] http://s.apache.org/yC http://people.apache.org/~simonetripodi/ http://simonetripodi.livejournal.com/ http://twitter.com/simonetripodi http://www.99soft.org/ - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
On 5 December 2011 15:42, Gary Gregory garydgreg...@gmail.com wrote: Personally, I do not like annotations to describe the stability of an API. If it's public I can use it. The next release is binary and/or source compatible, just document how to migrate. No one is forcing me to upgrade. If your component is part of a larger application that may not be true, see below. If I upgrade, I am using a new pile of code and I must deal with that. That's OK if your code is stand-alone at the end of the food chain, and you have control over it. Commons components often are deeply embedded. Using .internal packages is an interesting way to go. But I do like documentation of some kind for things like immutability and thread-safety. We've started going down the path of what I call extreme versioning when we create new packages for new incompatible releases. Right now, binary incompatible - new package (I'm even going to include Maven artifact ID noise here). See below for the reason why that is generally necessary. But what about a change in behavior that is not compatible? Should that not lead to a new package? Depends why the behaviour changed. Is it a bug fix? Commons is a 'special' project because it includes so many components. It would be nice if all components played by the same rules. Strictly speaking, I think we are bound to do so. I would say the Commons components are special because they are likely to be deeply nested in applications, with many other components depending on them. It may not be possible to upgrade the other components all at once. Some may be impossible to replace. If two components in the same classpath need incompatible versions, it will in general be impossible to update unless the two versions can coexist. That is why we have the rules on package/Maven id changes, so there can be multiple versions of a Commons component on the same classpath, if the need arises. Because package changes are expensive to end users, we try to avoid them if at all possible. That is why it's worth striving for binary compatibility. Gary On Mon, Dec 5, 2011 at 10:21 AM, Christian Grobmeier grobme...@gmail.comwrote: Henri, I would love to see this as a Commons recommendation on the Wiki. As Stefan mentioned, in Compress we have @experimental annons (I actually added them). I like the idea to make up a public, rarely to break interface api and some not so public sometimes to break implementation. Maybe we should even consider to create an interface jar and an implementation jar of different versions. On the other hand this makes things complex - but anyway Cheers Christian On Sun, Dec 4, 2011 at 11:41 AM, henrib hen...@apache.org wrote: Keeping track as it evolves based on feedback; Goal is to allow easy definition, usage and check of stable APIs. An annotation and a package naming convention allow the project developer to clearly state when a class/method/field is not part of the stable contract despite a public/protected declaration but only of the internal part of the project. @internal annotated class/method or *internal* package mean use this at your own maintenance cost; those are not part of the public API. They can be used and extended but are subject to change between versions without @deprecated annotations. Those annotations and conventions should allow feeding a clirr report with the proper information to allow detection of unintended API breakage and may even allow creating IDE plugins to warn about usage. -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156552.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org -- http://www.grobmeier.de https://www.timeandbill.de - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org -- E-Mail: garydgreg...@gmail.com | ggreg...@apache.org JUnit in Action, 2nd Ed: http://goog_1249600977http://bit.ly/ECvg0 Spring Batch in Action: http://s.apache.org/HOqhttp://bit.ly/bqpbCK Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
On Mon, Dec 5, 2011 at 4:42 PM, Gary Gregory garydgreg...@gmail.com wrote: Personally, I do not like annotations to describe the stability of an API. If it's public I can use it. The next release is binary and/or source compatible, just document how to migrate. No one is forcing me to upgrade. If I upgrade, I am using a new pile of code and I must deal with that. Using .internal packages is an interesting way to go. It is fine, using annotations is not really a must have for me. I think similar stuff like .internal do the Cayenne developers. But I do like documentation of some kind for things like immutability and thread-safety. +1 We've started going down the path of what I call extreme versioning when we create new packages for new incompatible releases. Right now, binary incompatible - new package (I'm even going to include Maven artifact ID noise here). But what about a change in behavior that is not compatible? Should that not lead to a new package? Honestly, no clue. What do you think on making up some good interfaces for a components. For example, a Compress interface set for version 1. If we decide to change something, no problem - interfaces stay the same. When the interfaces change, the version number changes and this will probably lead to a packagename change. I would hate to see o.a.c.compress_2_1.bla btw. ;-) Commons is a 'special' project because it includes so many components. It would be nice if all components played by the same rules. Strictly speaking, I think we are bound to do so. Very much +1. There are so many differences. As a user I am totally lost on all the different things people do. Cheers Gary On Mon, Dec 5, 2011 at 10:21 AM, Christian Grobmeier grobme...@gmail.comwrote: Henri, I would love to see this as a Commons recommendation on the Wiki. As Stefan mentioned, in Compress we have @experimental annons (I actually added them). I like the idea to make up a public, rarely to break interface api and some not so public sometimes to break implementation. Maybe we should even consider to create an interface jar and an implementation jar of different versions. On the other hand this makes things complex - but anyway Cheers Christian On Sun, Dec 4, 2011 at 11:41 AM, henrib hen...@apache.org wrote: Keeping track as it evolves based on feedback; Goal is to allow easy definition, usage and check of stable APIs. An annotation and a package naming convention allow the project developer to clearly state when a class/method/field is not part of the stable contract despite a public/protected declaration but only of the internal part of the project. @internal annotated class/method or *internal* package mean use this at your own maintenance cost; those are not part of the public API. They can be used and extended but are subject to change between versions without @deprecated annotations. Those annotations and conventions should allow feeding a clirr report with the proper information to allow detection of unintended API breakage and may even allow creating IDE plugins to warn about usage. -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156552.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org -- http://www.grobmeier.de https://www.timeandbill.de - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org -- E-Mail: garydgreg...@gmail.com | ggreg...@apache.org JUnit in Action, 2nd Ed: http://goog_1249600977http://bit.ly/ECvg0 Spring Batch in Action: http://s.apache.org/HOqhttp://bit.ly/bqpbCK Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory -- http://www.grobmeier.de https://www.timeandbill.de - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
About the *internal* and @internal (package annotation); Of course if we could come up with a binding convention on the source layout and package name for all projects, it would be really nice (i.e. the *internal* package convention). (Oh, a common pom where only the source/test/site would be specific and allow automated reports and release vote publication... just dreaming out loud) But as a pragmatist, I'd rather have the @internal annotation that can serve as an intermediate, easy to use way to determine stability (both for the dev and the user) than nothing that slows down release cycles to a crawl; forcing projects to align on a source layout convention is likely bound to fail or at least a very (very very) long path. One of the goal is to allow at least easier - if not faster - release cycles; as devs, we'd be made easily aware that we are tinkering with the API contract and for release voting, it gets easier to control that we've not unintentionally screwed it up. Oh, and I do agree on the immutability / thread safety doc. :-) Cheers, Henrib -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4161225.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
Hi Henri, henrib wrote: It seems to me we have a hard time allowing both stability and usability. Stability of APIs does not contradict usability of the library, at least should not. Some of us are looking for very long term/stable/high-quality solutions because they need to aggregate lost of components, the stability users. Others are looking for best-of-breed/narrow scope/malleable libraries a with a guaranteed quality, the usability users. Thus the importance of clearly stating in our libraries what is 'stable' and what is 'usable'. The expressiveness in the language itself is not enough to properly describe the contract made regarding each party; i.e. sometimes things have to be public but should not be considered part of the API that follow the major,minor - deprecation. I believe we can come up with a set of agreeable rules to please both camps be through some naming convention in packages and annotations. As an kickstart proposal, may be something as simple as 2 annotations actually could be enough: @stable, @usable. @stable meaning the contract this API represents will not change without being first @deprecated @usable meaning this API is valid for this major version but may change in each minor with no warning We might also use a clear 'internal' sub-package name as a frontier delimiter on the same rule. Thoughts ? I don't see a real different between stable and usable. Either a user can rely on a functionality or not. If you want to improve a part of the API without breaking compatibility, you may always deprecate the part that should no longer be used, because it will vanish in the next major release. This is what we normally do for a new release. This is e.g. what we've done with commons-io (although we improved the interface for generics). If it is a real redesign of the API (like lang3), we make it possible to use old and new versions side-by-side with new package name and artifactId to avoid unresolvable dependency situations for our users. I am all for 'internal' packages. IMHO it is not necessary to name a package as 'internal' as long as it is clearly documented, but it is definitely a better indication. It's definitely the right approach to exclude internal packages from clirr, personally I'd even exclude internal packages from Javadoc. The risc of usage must be clear to every user. However, I don't believe that annotations will really help. I'd separate internal stiff on package boundary and anything else is part of the public API. If you start to mix different annotations within one package, all you get is confusion. Cheers, Jörg - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
The part I'm struggling with is that if these are annotations vs just javadoc tags then I would expect some kind of either compile time or runtime behavior (or both). It seems that you are proposing javadoc tags instead? If not what behavior would the annotations cause? Ralph On Dec 3, 2011, at 5:22 PM, Phil Steitz wrote: On 12/2/11 3:45 PM, henrib wrote: It seems to me we have a hard time allowing both stability and usability. Stability of APIs does not contradict usability of the library, at least should not. Some of us are looking for very long term/stable/high-quality solutions because they need to aggregate lost of components, the stability users. Others are looking for best-of-breed/narrow scope/malleable libraries a with a guaranteed quality, the usability users. Thus the importance of clearly stating in our libraries what is 'stable' and what is 'usable'. The expressiveness in the language itself is not enough to properly describe the contract made regarding each party; i.e. sometimes things have to be public but should not be considered part of the API that follow the major,minor - deprecation. I believe we can come up with a set of agreeable rules to please both camps be through some naming convention in packages and annotations. As an kickstart proposal, may be something as simple as 2 annotations actually could be enough: @stable, @usable. @stable meaning the contract this API represents will not change without being first @deprecated @usable meaning this API is valid for this major version but may change in each minor with no warning We might also use a clear 'internal' sub-package name as a frontier delimiter on the same rule. Thoughts ? I applaud the initiative and creative suggestion above. I wonder, though, what users would make of it. My first thought as a user would be to avoid ever using the unstable stuff but I can imagine scenarios where I might. In practical terms, it might be hard to decide what to put where. Can you provide some examples based on recent RCs? An easy baby step that I could personally get behind - and actually need in [math] - is adopting the .internal package name convention for classes that need to be public because they are used in multiple packages, but which are not intended for use by external applications and effectively exempt from version compatibility requirements. That could by itself provide a workaround for a lot of these issues. Phil Best regards, Henri -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4150322.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
On 2011-12-04, henrib wrote: When trying to release JEXL 2.1, the API was disrupted and the clirr report was outputing lots of clutter. As the dev, it became very hard to understand whether the change was actually breaking the intended stable API or just some internal methods or class. Would you have known at the point when JEXL 2.0.1 has been released which APIs you'd mark up as @stable or @usable? Stefan - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
Stefan Bodewig wrote Would you have known at the point when JEXL 2.0.1 has been released which APIs you'd mark up as @stable or @usable? Yes for most and in doubt, I could have marked them @usable (or @internal which may be a better term). -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156394.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
ralph.goers @dslextreme.com wrote The part I'm struggling with is that if these are annotations vs just javadoc tags then I would expect some kind of either compile time or runtime behavior (or both). It seems that you are proposing javadoc tags instead? If not what behavior would the annotations cause? I'm not versed enough in Javadoc but I believe annotation carry more processing power. The information can remain in the executable and allow post build analysis. To feed a clirr report, it seems we'd need to introspect the classes/methods to find those @internal. One could even dream of a -your favorite IDE here- plugin that warns you when using one of those. If there is an easy / easier practical solution that could serve the same purpose, I'm all for it! -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156415.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
Keeping track as it evolves based on feedback; Goal is to allow easy definition, usage and check of stable APIs. An annotation and a package naming convention allow the project developer to clearly state when a class/method/field is not part of the stable contract despite a public/protected declaration but only of the internal part of the project. @internal annotated class/method or *internal* package mean use this at your own maintenance cost; those are not part of the public API. They can be used and extended but are subject to change between versions without @deprecated annotations. Those annotations and conventions should allow feeding a clirr report with the proper information to allow detection of unintended API breakage and may even allow creating IDE plugins to warn about usage. -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156552.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
On 4 December 2011 10:41, henrib hen...@apache.org wrote: Keeping track as it evolves based on feedback; Goal is to allow easy definition, usage and check of stable APIs. +1, agree that we need to be clearer about what the intended external API is. An annotation and a package naming convention allow the project developer to clearly state when a class/method/field is not part of the stable contract despite a public/protected declaration but only of the internal part of the project. +1 @internal annotated class/method or *internal* package mean use this at your own maintenance cost; those are not part of the public API. They can be used and extended but are subject to change between versions without @deprecated annotations. +1. I prefer the use of a separate internal/experimental package name; seems much more obvious than an embedded annotation. Also much more obvious when setting up Clirr exclusions. I think it's worth having both internal and experimental packages (and annotations): - internal = not likely ever to be part of the external API - experimental = may one day become part of the external API However, I'm not yet sure how we get around the binary incompatibilities that result from renaming a package to internal or experimental (the reverse should be OK, as we don't promise anything) Those annotations and conventions should allow feeding a clirr report with the proper information to allow detection of unintended API breakage and may even allow creating IDE plugins to warn about usage. Clirr can already be told to ignore packages and classes. If it were possible to control this via annotations, I would hope that the report would show which classes had been excluded from consideration. At least with explicit exclusions in the POM it's fairly easy to see this information in one place. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
Since it may need clarification; The idea would be to allow a clirr report to give accurate analysis of whether the external / stable API has been modified. Methods or classes annotated as @stable, could not change from one version to another before they are @deprecated. Methods or classes annotated as @unstable (rather than @usable) could change between versions. The net result would be a good sense of whether the actual stable API is broken by a version and avoid lengthy discussions like the one we just had... Wouldn't this be possible to add to our toolbox as a clirr plugin of some kind? -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4154703.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
On 12/2/11 3:45 PM, henrib wrote: It seems to me we have a hard time allowing both stability and usability. Stability of APIs does not contradict usability of the library, at least should not. Some of us are looking for very long term/stable/high-quality solutions because they need to aggregate lost of components, the stability users. Others are looking for best-of-breed/narrow scope/malleable libraries a with a guaranteed quality, the usability users. Thus the importance of clearly stating in our libraries what is 'stable' and what is 'usable'. The expressiveness in the language itself is not enough to properly describe the contract made regarding each party; i.e. sometimes things have to be public but should not be considered part of the API that follow the major,minor - deprecation. I believe we can come up with a set of agreeable rules to please both camps be through some naming convention in packages and annotations. As an kickstart proposal, may be something as simple as 2 annotations actually could be enough: @stable, @usable. @stable meaning the contract this API represents will not change without being first @deprecated @usable meaning this API is valid for this major version but may change in each minor with no warning We might also use a clear 'internal' sub-package name as a frontier delimiter on the same rule. Thoughts ? I applaud the initiative and creative suggestion above. I wonder, though, what users would make of it. My first thought as a user would be to avoid ever using the unstable stuff but I can imagine scenarios where I might. In practical terms, it might be hard to decide what to put where. Can you provide some examples based on recent RCs? An easy baby step that I could personally get behind - and actually need in [math] - is adopting the .internal package name convention for classes that need to be public because they are used in multiple packages, but which are not intended for use by external applications and effectively exempt from version compatibility requirements. That could by itself provide a workaround for a lot of these issues. Phil Best regards, Henri -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4150322.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
I applaud the initiative and creative suggestion above. I wonder, though, what users would make of it. My first thought as a user would be to avoid ever using the unstable stuff but I can imagine scenarios where I might. Hi, I was wondering the same thing, from a user perspective too. I would avoid using the unstable classes too, and would like to have a way to know if any unstable classes are being used in one of my projects :) Having a quick glance on clirr maven plug-in site, I couldn't find much about its configuration. What if instead of adding these annotations, we suggested this as configuration to clirr? This way, instead of using annotations, we would use something similar to: configuration stable classorg.apache/class /stable /configuration And clirr wouldn't report on classes not listed in the configuration. Just food for thought :-) Cheers, Bruno P. Kinoshita http://kinoshita.eti.br http://tupilabs.com De: Phil Steitz phil.ste...@gmail.com Para: Commons Developers List dev@commons.apache.org Enviadas: Sábado, 3 de Dezembro de 2011 23:22 Assunto: Re: [RELEASE PROCESS] Stability versus usability On 12/2/11 3:45 PM, henrib wrote: It seems to me we have a hard time allowing both stability and usability. Stability of APIs does not contradict usability of the library, at least should not. Some of us are looking for very long term/stable/high-quality solutions because they need to aggregate lost of components, the stability users. Others are looking for best-of-breed/narrow scope/malleable libraries a with a guaranteed quality, the usability users. Thus the importance of clearly stating in our libraries what is 'stable' and what is 'usable'. The expressiveness in the language itself is not enough to properly describe the contract made regarding each party; i.e. sometimes things have to be public but should not be considered part of the API that follow the major,minor - deprecation. I believe we can come up with a set of agreeable rules to please both camps be through some naming convention in packages and annotations. As an kickstart proposal, may be something as simple as 2 annotations actually could be enough: @stable, @usable. @stable meaning the contract this API represents will not change without being first @deprecated @usable meaning this API is valid for this major version but may change in each minor with no warning We might also use a clear 'internal' sub-package name as a frontier delimiter on the same rule. Thoughts ? I applaud the initiative and creative suggestion above. I wonder, though, what users would make of it. My first thought as a user would be to avoid ever using the unstable stuff but I can imagine scenarios where I might. In practical terms, it might be hard to decide what to put where. Can you provide some examples based on recent RCs? An easy baby step that I could personally get behind - and actually need in [math] - is adopting the .internal package name convention for classes that need to be public because they are used in multiple packages, but which are not intended for use by external applications and effectively exempt from version compatibility requirements. That could by itself provide a workaround for a lot of these issues. Phil Best regards, Henri -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4150322.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
On 2011-12-02, henrib wrote: It seems to me we have a hard time allowing both stability and usability. Stability of APIs does not contradict usability of the library, at least should not. I'm glad you say that right at the beginning as the versus in the subject line seems to imply something else. 8-) Some of us are looking for very long term/stable/high-quality solutions because they need to aggregate lost of components, the stability users. Others are looking for best-of-breed/narrow scope/malleable libraries a with a guaranteed quality, the usability users. [Aside: is best-of-breed really impossible in a stable environment?] I don't think this is all there is to it. As one of the few people who still see value in Gump I tend to be in the stability camp - if there really are only these two choices. But it is more about the impact a new release has on the users than the number of components anybody aggregates. I don't think anybody likes the idea of having to modify code every time you update your dependencies. Thus the importance of clearly stating in our libraries what is 'stable' and what is 'usable'. While I like the idea to explicitly mark what you consider a stable/reliable API I don't think I like the tags. Or at least the tag usable. That it implies the stable parts are not usable makes me itch. As an kickstart proposal, may be something as simple as 2 annotations actually could be enough: @stable, @usable. @stable meaning the contract this API represents will not change without being first @deprecated @usable meaning this API is valid for this major version but may change in each minor with no warning We might also use a clear 'internal' sub-package name as a frontier delimiter on the same rule. Maybe we actually have three sorts of public APIs * APIs that we promise not to break unless we perform a major relase in which case we also change package names (and artifactIds). This is what you call @stable. * APIs that may break in minor releases. What you call @usable There is some danger to it in that you mark too many parts unstable and forget about them. I really think users prefer stable APIs to begin with unless the unstable ones offer important features and promise to become stable at one point in time. Compress has a package that has *experimental* warnings in Javadocs all over the place. It has carried this label for four minor relases now. Is it still experimental? I think anything not @stable needs to be revisited from time to time. * APIs that are only public for technical reasons but really are internal to the component. I think these are different from what you call @usable. And these should be allowed to change without warning as long as users are aware of the policy. So yes, I understand and agree that we sometimes want to add features and push them out to users before we understand them well enough to provide a stable API. And I really welcome any approach of explicitly marking those parts so that users - and people reviewing releases - know what to expect. But I also think the non-stable APIs have to be reconsidered from time to time and eventually become stable. Stefan - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [RELEASE PROCESS] Stability versus usability
Phil Steitz wrote In practical terms, it might be hard to decide what to put where. Can you provide some examples based on recent RCs? When trying to release JEXL 2.1, the API was disrupted and the clirr report was outputing lots of clutter. As the dev, it became very hard to understand whether the change was actually breaking the intended stable API or just some internal methods or class. Then a lot of effort - thanks to sebb - had to be spent just to check and amend the code to restore the contract. The findbugs, cobertura, chekstyle reports mostly allow to assess quality, a usable clirr report would give us a good view of stability. Phil Steitz wrote An easy baby step that I could personally get behind - and actually need in [math] - is adopting the .internal package name convention For new packages or during major code overhaul, it definitely does the job. But it might be unpractical and requires lots of code moving around; I'm currently trying to achieve this with JEXL3 and it is a major refactor. Plus it requires creating interfaces or abstract classes to clearly delineate the API; it tilts the balance of effort towards stability and hinders the ability to add features (in the same timeframe) thus slows down innovation. The annotation would be convenient to (re)decorate code since it is very lightweight, easy to use and control. Instead of @unstable / @usable, may be an @internal annotation would carry the proper information and would follow the same idea as the package name. @internal annotated class/method or *internal* package mean use this at your own maintenance cost; it still allows users to code using them, does not forcibly close extensibility thus preserve innovative contributions and provides a clearer view of the stable contract. Seems like a win-win. Best regards, Henrib -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156330.html Sent from the Commons - Dev mailing list archive at Nabble.com. - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
