I do not agree that classes that are public belong to the public API. It's rather well-known that when complex subpackage structures are created, there is no other way to share classes except to make them public. That is why, imo, the javadocs be produced in 2: one API that is officially supportable and for public consumption (i.e., not java technical terms but the social term) and one that is for the internal guts. Sorry users if you relied on the latter, but that's too bad -- unless it is not explicitly stated as such.
I would strongly suggest that Struts 2.1 refactor itself, if necessary, to separate out the public and internal API and produce two distrinct javadocs and source bundles based on these. Since 2.1 is already incompatible for plugins, I think it's the perfect excuse to not let the problem linger any more. Paul On Thu, Feb 21, 2008 at 3:55 PM, Brian Pontarelli <[EMAIL PROTECTED]> wrote: > Don Brown wrote: > > On 2/22/08, Brian Pontarelli <[EMAIL PROTECTED]> wrote: > > > >> Here's an example... The XWork configuration API changed to the > builder > >> pattern. This is probably a good thing, but required any plugin using > it > >> to make significant changes and re-compile. This change wasn't > >> compatible and there are ways to make these types of changes while not > >> impacting compatibility. Then it doesn't matter what the version > numbers > >> are. You deprecate things correctly and then remove them on a defined > >> schedule. > >> > > > > I disagree - we should be able to make internal changes between minor > > versions without deprecations where necessary and I would consider > > this necessary. By preserving the constructors and setter methods on > > the configuration entities, we wouldn't have gained any of the > > immutable benefits of the builders, and therefore, the bugs would have > > continued to exist. > > > > There is a significant distinction between changing an internal API > > and an external one. The number of people that were affected by this > > change was probably less than 10, as most users aren't creating > > ActionConfig objects. > > > Yep and those APIs are now public. They are no longer internal because > anyone can plug into the configuration system via a plugin, web.xml, > struts.xml, etc. Therefore, they should eventually stop changing and > have a well defined API plan for making incompatible changes. It > shouldn't matter if 10 or 1,000 people are using them, I feel that once > they are public they need to be controlled. > > >> But, I will say this... Struts 2 doesn't have any compatibility > >> definition at all. Versions 2.1.0 and 2.1.1 might be incompatible and > >> 2.1.5 and 2.2.7 might be compatible. This makes it impossible for > tools > >> like Ivy and Savant to manage Struts dependencies correctly. > Therefore, > >> I think it is VITAL that we pick a compatibility model and stick to > it. > >> > > > > Well, the Struts project has always had a defined strategy to guide > > changes and deprecations, although I can't seem to find it on the > > website right now. Also, each release plan includes notes where > > incompatibilities are listed. What more do you suggest we do? > > > I don't think this is necessarily true. I couldn't find anything stating > how the public APIs would be compatible across versions anywhere. Having > worked deeply in dependency management for enormously large applications > I can say that projects need to define a compatibility strategy and a > versioning scheme that allows tools like Maven, Savant, Ivy, etc to > figure out which version to use. Here's an example: > > project A -> library B 1.0 -> library C 1.1 -> library D 1.3 > project A -> struts 2.0.6 > > library C -> library F -> struts 2.1.1 > > library B -> library G -> struts 2.0.12 > > > -> means dependency. > > As you can see, these libraries (which might be plugins or whatever) are > using different versions of Struts. How is the build supposed to > determine which version to use? Which versions are compatible? Should > the build complain that 2.1.1 isn't compatible? Should it just pick > 2.1.1 because it is the latest version? Should the maintainer of library > F revert back to 2.0.12 or some other version? > > This is a simple case and I've seen much worse. > > The solution is this: > > 1. Pick a versioning scheme. I suggest that minor numbers indicate > compatibility such that 2.1.x are all compatible but 2.1 is not > compatible with 2.2. This seems to be the pattern. This is commonly > referred to as "patch" compatibility since things are only compatible > across patch version numbers like 2.1.1 and 2.1.2. > > 2. Tell developers that if the minor numbers in the version aren't > changing, they can't break any public APIs runtime compatibility. > > That should be it. Simple, straight-forward and still allows each > release to have its own version number. Then the tools can correctly > manage dependencies. > > -bp > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > >
