You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Brian Pontarelli <br...@pontarelli.com> on 2008/02/20 23:36:37 UTC
API Compatibility
>> The API has yet to be solidified and there are a few things that I'd
>> still like to discuss and possibly change in that regard. My main goal
>> is to ensure backwards compatibility in the convention plugin API.
>>
>
> My thinking is like this:
> upgrading from [today's convention-plugin] to [final convention-plugin]
> will be much easier than upgrading from [codebehind] to the [final
> convention-plugin].
>
True. The changes will probably not impact most applications, but will
be API changes and not compatible.
>> Furthermore, I think we should all start thinking about when the "true"
>> stable release of XWork and Struts2 will be.
>>
>
> Isn't a GA release meant to be a "true stable release"?
> I think to know what you want to say, but I am still somewhat confused about
> why releases in s2 are working the way they do.
>
It depends on your versioning system. I prefer for all minor numbers
(2.x) to be compatible and all major numbers (x.0) to be incompatible
for the API perspective. I also feel that patches numbers (2.1.x) should
not add or subtract features. Therefore, the schema I use GAs don't
measure compatibility, the version numbers to. In my world you release
GAs for majors, minors and patches when they are final. If the release
isn't final, it uses a signifier like A, B, RC, M. For example,
2.1.1-RC1 would be the first release candidate and 2.1.1 would be the GA
final release. Struts versioning is much different though.
>> I think it makes sense to
>> target the next release and jump up to 2.5 or some number to indicate
>> stable APIs. This would include a number of API clean-ups, OGNL
>> replacement and a few other things that will severely break plugins and
>> applications. After that release, API changes should be compatible so
>> that plugins and applications can be upgraded without requiring
>> re-compiling.
>>
>
> I am quite sure there will rise another list with new issues that should be
> resolved before a "true" release in some time...
> In my oppinion, API stability is nothing that comes with reaching some feature
> set or project milestone. This would imply stopping innovation at that point.
> For me, API stability needs to be some kind of project goal or philosophy -
> which needs to be enforced by defining commonly accepted rules.
>
I agree for the most part, but also use version numbers to imply API
freeze and compatibility. Innovation and API compatibility are not
mutually exclusive. Folks just have to understand what they can and
cannot do to APIs. For example, you cannot remove any methods or classes
otherwise, it isn't compatible. You can add new methods and classes and
this implies the ability to innovate. Deprecation can also be used
correctly (not like the JDK) to handle API changes between major versions.
> But my impression is that this is no (important) goal for s2, and I can hardly
> imagine that it will be one day just because it gets to a point where
> _today's_ most wanted features are implemented.
>
Not yet, but I want to make it one. I think since the plugin system
allows developers access to APIs that were at one point internal, it
changes things quite a bit. These APIs are now public and need to be
stabilized at some point. Otherwise we will end up having developers who
are constantly battling with upgrading plugins and applications and get
turned off by Struts.
> But maybe this is worth a new thread...
>
Agreed ;)
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
On 2/22/08, Paul Benedict <pb...@apache.org> wrote:
> 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.
I'd love to see that as well, since we were half-way there with Bob
creating a new API that would even shield XWork classes, drastically
simplifying the API surface area for Struts users. Unfortunately,
there is still a lot of work to be done, and as it would greatly
affect all Struts applications, the earliest it could be introduced
would be Struts 3.
Don
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Paul Benedict <pb...@apache.org>.
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 <br...@pontarelli.com>
wrote:
> Don Brown wrote:
> > On 2/22/08, Brian Pontarelli <br...@pontarelli.com> 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: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Antonio Petrelli wrote:
> Wow what a long thread and all in the night :-) (well, at least for Europe).
> Sincerely I don't see the problem of changing the name of "Struts 2.1.x" to
> "Struts 3.0.x". It's just a version name change.
> IMHO if you change the API (read: public, protected and package-friendly
> members) instead of deprecating them, we *cannot* release a 2.1.x version.
> If we developers are too lazy to deprecate members, well, we either choose
> to re-create deprecated members, or we should roll a 3.0 version
> In fact, if we roll out a 3.0 version, Struts users will be sure that these
> changes are incompatible.
>
Same here.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Antonio Petrelli <an...@gmail.com>.
2008/2/22, Al Sutton <al...@alsutton.com>:
>
> I see where you're coming from, but I really don't think the leap from
> S2.0
> to the current S2.1 is anywhere near the leap from S1 to S2
+1, in fact I think (always it's my humble opinion) that putting Webwork
under the Struts 2 name was a *stupid* marketing move. IMHO it would have
been better to incubate Webwork with its own name.
hence why I'm
> in favour of the 2.1 because I feel it reflects that although there are
> some
> changes, many of the core concepts are the same and, in many cases,
> changes
> will be limited to small sections of the app (such as config files an
> updates to specific API usage), as opposed to major changes to tag names,
> functionality, and design concepts.
Ok, but in this case the extraction of the API part would be mandatory: this
way we say that the API are "almost" immutable (eventually with
deprecations), the rest is the implementation, and it can change.
But since Struts 2.0.x has no API part (I sincerely don't know why it was
removed in Struts 2.1.x), a "major" change (in the version number) "usually"
is needed, if we decide to create it.
I don't see why Struts should follow its own rules, only to preserve the
difference between Struts 1 and 2.
Antonio
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Al Sutton wrote:
> Antonio,
>
> I see where you're coming from, but I really don't think the leap from
> S2.0 to the current S2.1 is anywhere near the leap from S1 to S2,
> hence why I'm in favour of the 2.1 because I feel it reflects that
> although there are some changes, many of the core concepts are the
> same and, in many cases, changes will be limited to small sections of
> the app (such as config files an updates to specific API usage), as
> opposed to major changes to tag names, functionality, and design
> concepts.
I think these are good points. The key isn't to never break things, but
to structure it well. That is why I'd like to break everything, clean it
all up and then move forward from something like 3.0 as the API freeze
for all release up to 4.0. That's really what I'm after. Then I can tell
the tools to check compatibility at the major number.
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Al Sutton <al...@alsutton.com>.
Antonio,
I see where you're coming from, but I really don't think the leap from S2.0
to the current S2.1 is anywhere near the leap from S1 to S2, hence why I'm
in favour of the 2.1 because I feel it reflects that although there are some
changes, many of the core concepts are the same and, in many cases, changes
will be limited to small sections of the app (such as config files an
updates to specific API usage), as opposed to major changes to tag names,
functionality, and design concepts.
Al.
----- Original Message -----
From: "Antonio Petrelli" <an...@gmail.com>
To: "Struts Developers List" <de...@struts.apache.org>
Sent: Friday, February 22, 2008 8:08 AM
Subject: Re: API Compatibility
> Wow what a long thread and all in the night :-) (well, at least for
> Europe).
> Sincerely I don't see the problem of changing the name of "Struts 2.1.x"
> to
> "Struts 3.0.x". It's just a version name change.
> IMHO if you change the API (read: public, protected and package-friendly
> members) instead of deprecating them, we *cannot* release a 2.1.x version.
> If we developers are too lazy to deprecate members, well, we either choose
> to re-create deprecated members, or we should roll a 3.0 version
> In fact, if we roll out a 3.0 version, Struts users will be sure that
> these
> changes are incompatible.
>
> Just my 2 eurocents.
>
> Antonio
>
> 2008/2/22, Al Sutton <al...@alsutton.com>:
>>
>> Just so we're all on the same page, can I put forward the following as a
>> version numbering plan which would seem to reflect most peoples views;
>>
>> 2.0.x - New releases shouldn't alter the public API unless absolutley
>> neccessary (e.g. something is a security risk).
>>
>> 2.1.x (pre-first GA) - Changes to the public API allowed, all pre-first
>> GA
>> releases are evolving and are released to allow users to get a feel for
>> the
>> direction 2.1 is going in and comment on it in the users list.
>>
>> 2.1.x (post-first GA) - New releases should not alter the public API
>> unless
>> absolutley neccessary (e.g. something is a security risk).
>>
>> 2.2 - Needed if there are post-first GA 2.1.x changes which will break
>> parts
>> of the public API and the changes are only functional enhancements.
>>
>> 3.x - Only needed if there are changes to large parts of the public API
>> which would break almost every S2.x app out there (in the same way the
>> 1.x
>> to 2.x did).
>>
>> Does this sound OK?
>>
>>
>> Al.
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>> For additional commands, e-mail: dev-help@struts.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Antonio Petrelli <an...@gmail.com>.
Wow what a long thread and all in the night :-) (well, at least for Europe).
Sincerely I don't see the problem of changing the name of "Struts 2.1.x" to
"Struts 3.0.x". It's just a version name change.
IMHO if you change the API (read: public, protected and package-friendly
members) instead of deprecating them, we *cannot* release a 2.1.x version.
If we developers are too lazy to deprecate members, well, we either choose
to re-create deprecated members, or we should roll a 3.0 version
In fact, if we roll out a 3.0 version, Struts users will be sure that these
changes are incompatible.
Just my 2 eurocents.
Antonio
2008/2/22, Al Sutton <al...@alsutton.com>:
>
> Just so we're all on the same page, can I put forward the following as a
> version numbering plan which would seem to reflect most peoples views;
>
> 2.0.x - New releases shouldn't alter the public API unless absolutley
> neccessary (e.g. something is a security risk).
>
> 2.1.x (pre-first GA) - Changes to the public API allowed, all pre-first GA
> releases are evolving and are released to allow users to get a feel for
> the
> direction 2.1 is going in and comment on it in the users list.
>
> 2.1.x (post-first GA) - New releases should not alter the public API
> unless
> absolutley neccessary (e.g. something is a security risk).
>
> 2.2 - Needed if there are post-first GA 2.1.x changes which will break
> parts
> of the public API and the changes are only functional enhancements.
>
> 3.x - Only needed if there are changes to large parts of the public API
> which would break almost every S2.x app out there (in the same way the 1.x
> to 2.x did).
>
> Does this sound OK?
>
>
> Al.
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
Re: API Compatibility
Posted by Antonio Petrelli <an...@gmail.com>.
2008/2/22, Brian Pontarelli <br...@pontarelli.com>:
> In order to support the current model you would need to tell tools like
> Savant and Ivy that 2.1.0 is not compatible with 2.1.1 but 2.1.1 is
> compatible with 2.1.2. In essence you would need a file that lists the
> compatibility that those tools could use when verifying the project.
In Struts (and also in Tiles) we choose the compatibility voting for
its quality.
Alpha: added API can change severly in _future_ version.
Beta: added API (since the first Alpha) can change but not so much.
GA: added API are stabilized and will not change.
Notice the use of the term "added API". This means that usually the
backward compatibility should follow the version numbering scheme.
Antonio
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
This one looks good a good resource. Sun also has one here:
http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html
Section 13.4 of the java language specification covers compatibility
stuff. Sun also has some good information about versioning of JAR files
and distributed objects, which apply equally as well.
-bp
Paul Benedict wrote:
> I think it will benefit everyone to read this three part piece on evolving
> APIs:
>
> http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs
>
> Paul
>
> On Thu, Feb 21, 2008 at 10:37 PM, Martin Cooper <ma...@apache.org> wrote:
>
>
>> On Thu, Feb 21, 2008 at 7:03 PM, Brian Pontarelli <br...@pontarelli.com>
>> wrote:
>>
>>
>>> Don Brown wrote:
>>>
>>>> Yes, you are missing my original point #2 - "We need to be able to do
>>>> "alpha" releases to get new, experimental features into the community
>>>> for testing." I need a way to create an alpha release for 2.1 to hand
>>>> off to our community for feedback, but if all releases require a
>>>> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
>>>>
>>>> Public API changes take a while and lots of feedback to really get
>>>> right, so going six months without a release is not acceptable, IMO.
>>>>
>>>>
>>> I think we will have to disagree on this point. From my perspective
>>> these things are mutually exclusive. You can make experimental new
>>> features and changes without breaking compatibility. It still comes down
>>> to being pragmatic about your changes and ensuring things don't break
>>> severely. However, I want to make it clear that I'm NOT advocating never
>>> breaking compatibility. I just want a versioning scheme that ensures
>>> tools can figure it out.
>>>
>>> As a separate question, why can't the scheme be changed for Struts 2
>>> specifically? I get a sense that everyone is saying, "don't even think
>>> about changing it because it will never happen." If something isn't
>>> working and there are better ways to handle things, isn't it our jobs as
>>> engineers to fix them?
>>>
>> Before you start such a discussion, I would suggest that you take the time
>> to look back, in the archives, through the several years worth of
>> discussions in that got us to the point we're at today, so that you
>> _fully_
>> understand the context and the reasoning behind the scheme that we have
>> now.
>> I really, really don't want to rehash those discussions, because they are
>> always very prolonged, they consume vast amounts of time, energy and
>> enthusiasm, and they seriously eat into the real development effort
>> because
>> of that. I'd much prefer to see the team's effort go into making Struts
>> the
>> best that it can be rather than go off down that rat hole.
>>
>> The one tip I will give you before you head to the archives is that our
>> process is basically the same as the ones used by HTTPD and Tomcat, two of
>> the most long-standing projects in all of the ASF, so it's not something
>> we
>> made up off the top of our heads. It's been proven in the real world for
>> more than a decade.
>>
>> All of that said, once you fully understand all of the history, and if you
>> still feel you have a really compelling reason for the project to switch
>> to
>> another scheme, you are of course absolutely free to propose it. But do
>> spend the time first, so that you realise what you are letting yourself -
>> and the rest of us - in for, and expect to significantly slow down
>> progress
>> on the code until that discussion comes to closure.
>>
>> --
>> Martin Cooper
>>
>>
>>
>>
>>> -bp
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>>> For additional commands, e-mail: dev-help@struts.apache.org
>>>
>>>
>>>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Al Sutton <al...@alsutton.com>.
The problem with the method you mention is that with the apache release
voting system we don't know the quality of the release until after it's been
made and voted on, so we can't release an "alpha" version because until the
vote has happened it may turn out to be a full release.
I also believe it's down to the tool to accommodate the releases of the
project, and we shouldn't define a release numbering system around what
suits any particular tool.
Al.
----- Original Message -----
From: "Brian Pontarelli" <br...@pontarelli.com>
To: "Struts Developers List" <de...@struts.apache.org>
Sent: Friday, February 22, 2008 2:54 PM
Subject: Re: API Compatibility
> Al Sutton wrote:
>> Just so we're all on the same page, can I put forward the following as a
>> version numbering plan which would seem to reflect most peoples views;
>>
>> 2.0.x - New releases shouldn't alter the public API unless absolutley
>> neccessary (e.g. something is a security risk).
>>
>> 2.1.x (pre-first GA) - Changes to the public API allowed, all pre-first
>> GA releases are evolving and are released to allow users to get a feel
>> for the direction 2.1 is going in and comment on it in the users list.
>>
>> 2.1.x (post-first GA) - New releases should not alter the public API
>> unless absolutley neccessary (e.g. something is a security risk).
>>
>> 2.2 - Needed if there are post-first GA 2.1.x changes which will break
>> parts of the public API and the changes are only functional enhancements.
>>
>> 3.x - Only needed if there are changes to large parts of the public API
>> which would break almost every S2.x app out there (in the same way the
>> 1.x to 2.x did).
>>
>> Does this sound OK?
> This scheme doesn't work because you can't tell a tool generically how
> things are compatible. The scheme needs a method for doing release while
> still breaking compatibility. This is where traditionally libraries tend
> towards alpha, beta, milestone and release candidate numbering. Savant
> uses this model:
>
> 1.0-Ax
> 1.0-Bx
> 1.0-Mx
> 1.0-RCx
> 1.0
> 1.0.x
> 1.x
>
> In order to support the current model you would need to tell tools like
> Savant and Ivy that 2.1.0 is not compatible with 2.1.1 but 2.1.1 is
> compatible with 2.1.2. In essence you would need a file that lists the
> compatibility that those tools could use when verifying the project.
>
> -bp
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Al Sutton wrote:
> Just so we're all on the same page, can I put forward the following as
> a version numbering plan which would seem to reflect most peoples views;
>
> 2.0.x - New releases shouldn't alter the public API unless absolutley
> neccessary (e.g. something is a security risk).
>
> 2.1.x (pre-first GA) - Changes to the public API allowed, all
> pre-first GA releases are evolving and are released to allow users to
> get a feel for the direction 2.1 is going in and comment on it in the
> users list.
>
> 2.1.x (post-first GA) - New releases should not alter the public API
> unless absolutley neccessary (e.g. something is a security risk).
>
> 2.2 - Needed if there are post-first GA 2.1.x changes which will break
> parts of the public API and the changes are only functional enhancements.
>
> 3.x - Only needed if there are changes to large parts of the public
> API which would break almost every S2.x app out there (in the same way
> the 1.x to 2.x did).
>
> Does this sound OK?
This scheme doesn't work because you can't tell a tool generically how
things are compatible. The scheme needs a method for doing release while
still breaking compatibility. This is where traditionally libraries tend
towards alpha, beta, milestone and release candidate numbering. Savant
uses this model:
1.0-Ax
1.0-Bx
1.0-Mx
1.0-RCx
1.0
1.0.x
1.x
In order to support the current model you would need to tell tools like
Savant and Ivy that 2.1.0 is not compatible with 2.1.1 but 2.1.1 is
compatible with 2.1.2. In essence you would need a file that lists the
compatibility that those tools could use when verifying the project.
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Al Sutton <al...@alsutton.com>.
Just so we're all on the same page, can I put forward the following as a
version numbering plan which would seem to reflect most peoples views;
2.0.x - New releases shouldn't alter the public API unless absolutley
neccessary (e.g. something is a security risk).
2.1.x (pre-first GA) - Changes to the public API allowed, all pre-first GA
releases are evolving and are released to allow users to get a feel for the
direction 2.1 is going in and comment on it in the users list.
2.1.x (post-first GA) - New releases should not alter the public API unless
absolutley neccessary (e.g. something is a security risk).
2.2 - Needed if there are post-first GA 2.1.x changes which will break parts
of the public API and the changes are only functional enhancements.
3.x - Only needed if there are changes to large parts of the public API
which would break almost every S2.x app out there (in the same way the 1.x
to 2.x did).
Does this sound OK?
Al.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Paul Benedict <pb...@apache.org>.
I think it will benefit everyone to read this three part piece on evolving
APIs:
http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs
Paul
On Thu, Feb 21, 2008 at 10:37 PM, Martin Cooper <ma...@apache.org> wrote:
> On Thu, Feb 21, 2008 at 7:03 PM, Brian Pontarelli <br...@pontarelli.com>
> wrote:
>
> > Don Brown wrote:
> > > Yes, you are missing my original point #2 - "We need to be able to do
> > > "alpha" releases to get new, experimental features into the community
> > > for testing." I need a way to create an alpha release for 2.1 to hand
> > > off to our community for feedback, but if all releases require a
> > > unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
> > >
> > > Public API changes take a while and lots of feedback to really get
> > > right, so going six months without a release is not acceptable, IMO.
> > >
> > I think we will have to disagree on this point. From my perspective
> > these things are mutually exclusive. You can make experimental new
> > features and changes without breaking compatibility. It still comes down
> > to being pragmatic about your changes and ensuring things don't break
> > severely. However, I want to make it clear that I'm NOT advocating never
> > breaking compatibility. I just want a versioning scheme that ensures
> > tools can figure it out.
> >
> > As a separate question, why can't the scheme be changed for Struts 2
> > specifically? I get a sense that everyone is saying, "don't even think
> > about changing it because it will never happen." If something isn't
> > working and there are better ways to handle things, isn't it our jobs as
> > engineers to fix them?
>
>
> Before you start such a discussion, I would suggest that you take the time
> to look back, in the archives, through the several years worth of
> discussions in that got us to the point we're at today, so that you
> _fully_
> understand the context and the reasoning behind the scheme that we have
> now.
> I really, really don't want to rehash those discussions, because they are
> always very prolonged, they consume vast amounts of time, energy and
> enthusiasm, and they seriously eat into the real development effort
> because
> of that. I'd much prefer to see the team's effort go into making Struts
> the
> best that it can be rather than go off down that rat hole.
>
> The one tip I will give you before you head to the archives is that our
> process is basically the same as the ones used by HTTPD and Tomcat, two of
> the most long-standing projects in all of the ASF, so it's not something
> we
> made up off the top of our heads. It's been proven in the real world for
> more than a decade.
>
> All of that said, once you fully understand all of the history, and if you
> still feel you have a really compelling reason for the project to switch
> to
> another scheme, you are of course absolutely free to propose it. But do
> spend the time first, so that you realise what you are letting yourself -
> and the rest of us - in for, and expect to significantly slow down
> progress
> on the code until that discussion comes to closure.
>
> --
> Martin Cooper
>
>
>
> >
> > -bp
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> > For additional commands, e-mail: dev-help@struts.apache.org
> >
> >
>
Re: API Compatibility
Posted by Paul Benedict <pb...@apache.org>.
I don't know where my mind went... sorry, we had patch releases in 1.x :-)
On Fri, Feb 22, 2008 at 9:42 AM, Paul Benedict <pb...@apache.org> wrote:
> I propose this:
>
> Major point releases (1.0, 2.0, 3.0) is where Committers:
> * May add API signatures
> * May modify API signatures
> * May remove deprecated API.
>
> Minor point releases (2.0, 2.1, 2.2) is where Committers:
> * May add API signatures
> * May not modify API signatures
> * May deprecate API.
>
> Patch point releases (2.1.1, 2.1.2, 2.1.3) is where Committers:
> * May not add API signatures
> * May not modify API signatures
> * May deprecate API.
>
> Struts (2000-2006) in series 1.x has held to these rules except for the
> last, which we never had point releases. The Apache Commons library follows
> something very similar and as strict, and I believe is the
> quality/trust/confidence needed for upgrading.
>
> Paul
>
>
>
> On Fri, Feb 22, 2008 at 9:09 AM, Brian Pontarelli <br...@pontarelli.com>
> wrote:
>
> > Piero Sartini wrote:
> > > Am Freitag, 22. Februar 2008 00:05:53 schrieb Don Brown:
> > >
> > >> Yes, you are missing my original point #2 - "We need to be able to do
> > >> "alpha" releases to get new, experimental features into the community
> > >> for testing." I need a way to create an alpha release for 2.1 to hand
> > >> off to our community for feedback, but if all releases require a
> > >> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
> > >>
> > >> Public API changes take a while and lots of feedback to really get
> > >> right, so going six months without a release is not acceptable, IMO.
> > >>
> > >
> > > If these changes need feedback .. why not put them in alpha releases?
> > 2.2
> > > Alpha1, 2.2 Alpha2, etc
> > >
> > > For me, s.th. like this would be great:
> > > A.B.C.D
> > >
> > > D -> Error fixing, security patches, etc
> > > C -> new features, smaller api changes even incompatible ones
> > > B -> big changes, large refactorings, new approaches, etc.
> > > A -> Struts version
> > >
> > This would be sub-patch compatibility, which is fine and most tools
> > currently or could easily support this. That would mean that 2.1.1.0 and
> > 2.1.1.1 would be compatible, but 2.1.0 and 2.1.1 are not. Therefore, if
> > your project depended on 2.1.1.0 and transitively depended on 2.1.0.0,
> > the build would break, as it should.
> >
> > -bp
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> > For additional commands, e-mail: dev-help@struts.apache.org
> >
> >
>
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
It doesn't help your argument to use Maven as an example :) I think
it is pretty straight forward - all plugins have versions, only the
bundled plugins are versioned/released along with the rest of Struts
to make it simpler. If we gave each plugin its own version, which we
did with Struts 1, it gets really confusing really quickly what
versions are meant to go with what releases. For the occasional
third-party plugin with its own release cycle, this is a necessary
evil, but for the core plugins, it is a huge source of confusion to
users.
Don
On 2/23/08, Antonio Petrelli <an...@gmail.com> wrote:
> 2008/2/23, Al Sutton <al...@alsutton.com>:
>
> > So what happens if a plug-in is added to the core (e.g. a YUI and/or GWT
> > plugin to compliment the dojo one), does that necessitate a 2.2?
>
>
> This is The Good Question :-)
> As I wrote a lot of time before, IMHO every plugin should be treated
> as a different project, with its own version number, a-la Maven.
> This suggestion has not been taken into consideration and we are
> suffering the consequences, because lots of Struts 2 plugins are
> coming out day by day.
>
> Antonio
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Antonio Petrelli <an...@gmail.com>.
2008/2/23, Al Sutton <al...@alsutton.com>:
> So what happens if a plug-in is added to the core (e.g. a YUI and/or GWT
> plugin to compliment the dojo one), does that necessitate a 2.2?
This is The Good Question :-)
As I wrote a lot of time before, IMHO every plugin should be treated
as a different project, with its own version number, a-la Maven.
This suggestion has not been taken into consideration and we are
suffering the consequences, because lots of Struts 2 plugins are
coming out day by day.
Antonio
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Al Sutton <al...@alsutton.com>.
So what happens if a plug-in is added to the core (e.g. a YUI and/or GWT
plugin to compliment the dojo one), does that necessitate a 2.2?
Al.
----- Original Message -----
From: "Paul Benedict" <pb...@apache.org>
To: "Struts Developers List" <de...@struts.apache.org>
Sent: Friday, February 22, 2008 8:21 PM
Subject: Re: API Compatibility
> Al,
>
> The Apache voting system is totally oblivious to version numbers. Example:
>
> 1) Build 2.1.0 is put to vote
> 2) Voting on 2.1.0 fails
> 3) Build 2.1.1 is put to vote
> 4) Voting on 2.1.1 succeeds and is released
> 5) etc.
>
> Numbers do not bump based on the voting. Numbers are bumped based on a
> finished build.
>
> Paul
>
> On Fri, Feb 22, 2008 at 1:24 PM, Al Sutton <al...@alsutton.com> wrote:
>
>> It sounds good, but my question would be; what happens if a plugin is
>> deemed
>> good enough to include in the core?, would this count as an API addition
>> and
>> therefore justify a 2.2?
>>
>> Al.
>>
>> ----- Original Message -----
>> From: "Paul Benedict" <pb...@apache.org>
>> To: "Struts Developers List" <de...@struts.apache.org>
>> Sent: Friday, February 22, 2008 3:42 PM
>> Subject: Re: API Compatibility
>>
>>
>> >I propose this:
>> >
>> > Major point releases (1.0, 2.0, 3.0) is where Committers:
>> > * May add API signatures
>> > * May modify API signatures
>> > * May remove deprecated API.
>> >
>> > Minor point releases (2.0, 2.1, 2.2) is where Committers:
>> > * May add API signatures
>> > * May not modify API signatures
>> > * May deprecate API.
>> >
>> > Patch point releases (2.1.1, 2.1.2, 2.1.3) is where Committers:
>> > * May not add API signatures
>> > * May not modify API signatures
>> > * May deprecate API.
>> >
>> > Struts (2000-2006) in series 1.x has held to these rules except for the
>> > last, which we never had point releases. The Apache Commons library
>> > follows
>> > something very similar and as strict, and I believe is the
>> > quality/trust/confidence needed for upgrading.
>> >
>> > Paul
>> >
>> >
>> > On Fri, Feb 22, 2008 at 9:09 AM, Brian Pontarelli
>> > <br...@pontarelli.com>
>> > wrote:
>> >
>> >> Piero Sartini wrote:
>> >> > Am Freitag, 22. Februar 2008 00:05:53 schrieb Don Brown:
>> >> >
>> >> >> Yes, you are missing my original point #2 - "We need to be able to
>> do
>> >> >> "alpha" releases to get new, experimental features into the
>> community
>> >> >> for testing." I need a way to create an alpha release for 2.1 to
>> hand
>> >> >> off to our community for feedback, but if all releases require a
>> >> >> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3,
>> >> >> etc.
>> >> >>
>> >> >> Public API changes take a while and lots of feedback to really get
>> >> >> right, so going six months without a release is not acceptable,
>> >> >> IMO.
>> >> >>
>> >> >
>> >> > If these changes need feedback .. why not put them in alpha
>> >> > releases?
>> >> 2.2
>> >> > Alpha1, 2.2 Alpha2, etc
>> >> >
>> >> > For me, s.th. like this would be great:
>> >> > A.B.C.D
>> >> >
>> >> > D -> Error fixing, security patches, etc
>> >> > C -> new features, smaller api changes even incompatible ones
>> >> > B -> big changes, large refactorings, new approaches, etc.
>> >> > A -> Struts version
>> >> >
>> >> This would be sub-patch compatibility, which is fine and most tools
>> >> currently or could easily support this. That would mean that
>> >> 2.1.1.0and
>> >> 2.1.1.1 would be compatible, but 2.1.0 and 2.1.1 are not. Therefore,
>> >> if
>> >> your project depended on 2.1.1.0 and transitively depended on 2.1.0.0,
>> >> the build would break, as it should.
>> >>
>> >> -bp
>> >>
>> >>
>> >> ---------------------------------------------------------------------
>> >> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>> >> For additional commands, e-mail: dev-help@struts.apache.org
>> >>
>> >>
>> >
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>> For additional commands, e-mail: dev-help@struts.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Paul Benedict <pb...@apache.org>.
Al,
The Apache voting system is totally oblivious to version numbers. Example:
1) Build 2.1.0 is put to vote
2) Voting on 2.1.0 fails
3) Build 2.1.1 is put to vote
4) Voting on 2.1.1 succeeds and is released
5) etc.
Numbers do not bump based on the voting. Numbers are bumped based on a
finished build.
Paul
On Fri, Feb 22, 2008 at 1:24 PM, Al Sutton <al...@alsutton.com> wrote:
> It sounds good, but my question would be; what happens if a plugin is
> deemed
> good enough to include in the core?, would this count as an API addition
> and
> therefore justify a 2.2?
>
> Al.
>
> ----- Original Message -----
> From: "Paul Benedict" <pb...@apache.org>
> To: "Struts Developers List" <de...@struts.apache.org>
> Sent: Friday, February 22, 2008 3:42 PM
> Subject: Re: API Compatibility
>
>
> >I propose this:
> >
> > Major point releases (1.0, 2.0, 3.0) is where Committers:
> > * May add API signatures
> > * May modify API signatures
> > * May remove deprecated API.
> >
> > Minor point releases (2.0, 2.1, 2.2) is where Committers:
> > * May add API signatures
> > * May not modify API signatures
> > * May deprecate API.
> >
> > Patch point releases (2.1.1, 2.1.2, 2.1.3) is where Committers:
> > * May not add API signatures
> > * May not modify API signatures
> > * May deprecate API.
> >
> > Struts (2000-2006) in series 1.x has held to these rules except for the
> > last, which we never had point releases. The Apache Commons library
> > follows
> > something very similar and as strict, and I believe is the
> > quality/trust/confidence needed for upgrading.
> >
> > Paul
> >
> >
> > On Fri, Feb 22, 2008 at 9:09 AM, Brian Pontarelli <br...@pontarelli.com>
> > wrote:
> >
> >> Piero Sartini wrote:
> >> > Am Freitag, 22. Februar 2008 00:05:53 schrieb Don Brown:
> >> >
> >> >> Yes, you are missing my original point #2 - "We need to be able to
> do
> >> >> "alpha" releases to get new, experimental features into the
> community
> >> >> for testing." I need a way to create an alpha release for 2.1 to
> hand
> >> >> off to our community for feedback, but if all releases require a
> >> >> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
> >> >>
> >> >> Public API changes take a while and lots of feedback to really get
> >> >> right, so going six months without a release is not acceptable, IMO.
> >> >>
> >> >
> >> > If these changes need feedback .. why not put them in alpha releases?
> >> 2.2
> >> > Alpha1, 2.2 Alpha2, etc
> >> >
> >> > For me, s.th. like this would be great:
> >> > A.B.C.D
> >> >
> >> > D -> Error fixing, security patches, etc
> >> > C -> new features, smaller api changes even incompatible ones
> >> > B -> big changes, large refactorings, new approaches, etc.
> >> > A -> Struts version
> >> >
> >> This would be sub-patch compatibility, which is fine and most tools
> >> currently or could easily support this. That would mean that 2.1.1.0and
> >> 2.1.1.1 would be compatible, but 2.1.0 and 2.1.1 are not. Therefore, if
> >> your project depended on 2.1.1.0 and transitively depended on 2.1.0.0,
> >> the build would break, as it should.
> >>
> >> -bp
> >>
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> >> For additional commands, e-mail: dev-help@struts.apache.org
> >>
> >>
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
Re: API Compatibility
Posted by Al Sutton <al...@alsutton.com>.
It sounds good, but my question would be; what happens if a plugin is deemed
good enough to include in the core?, would this count as an API addition and
therefore justify a 2.2?
Al.
----- Original Message -----
From: "Paul Benedict" <pb...@apache.org>
To: "Struts Developers List" <de...@struts.apache.org>
Sent: Friday, February 22, 2008 3:42 PM
Subject: Re: API Compatibility
>I propose this:
>
> Major point releases (1.0, 2.0, 3.0) is where Committers:
> * May add API signatures
> * May modify API signatures
> * May remove deprecated API.
>
> Minor point releases (2.0, 2.1, 2.2) is where Committers:
> * May add API signatures
> * May not modify API signatures
> * May deprecate API.
>
> Patch point releases (2.1.1, 2.1.2, 2.1.3) is where Committers:
> * May not add API signatures
> * May not modify API signatures
> * May deprecate API.
>
> Struts (2000-2006) in series 1.x has held to these rules except for the
> last, which we never had point releases. The Apache Commons library
> follows
> something very similar and as strict, and I believe is the
> quality/trust/confidence needed for upgrading.
>
> Paul
>
>
> On Fri, Feb 22, 2008 at 9:09 AM, Brian Pontarelli <br...@pontarelli.com>
> wrote:
>
>> Piero Sartini wrote:
>> > Am Freitag, 22. Februar 2008 00:05:53 schrieb Don Brown:
>> >
>> >> Yes, you are missing my original point #2 - "We need to be able to do
>> >> "alpha" releases to get new, experimental features into the community
>> >> for testing." I need a way to create an alpha release for 2.1 to hand
>> >> off to our community for feedback, but if all releases require a
>> >> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
>> >>
>> >> Public API changes take a while and lots of feedback to really get
>> >> right, so going six months without a release is not acceptable, IMO.
>> >>
>> >
>> > If these changes need feedback .. why not put them in alpha releases?
>> 2.2
>> > Alpha1, 2.2 Alpha2, etc
>> >
>> > For me, s.th. like this would be great:
>> > A.B.C.D
>> >
>> > D -> Error fixing, security patches, etc
>> > C -> new features, smaller api changes even incompatible ones
>> > B -> big changes, large refactorings, new approaches, etc.
>> > A -> Struts version
>> >
>> This would be sub-patch compatibility, which is fine and most tools
>> currently or could easily support this. That would mean that 2.1.1.0 and
>> 2.1.1.1 would be compatible, but 2.1.0 and 2.1.1 are not. Therefore, if
>> your project depended on 2.1.1.0 and transitively depended on 2.1.0.0,
>> the build would break, as it should.
>>
>> -bp
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>> For additional commands, e-mail: dev-help@struts.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Paul Benedict <pb...@apache.org>.
I propose this:
Major point releases (1.0, 2.0, 3.0) is where Committers:
* May add API signatures
* May modify API signatures
* May remove deprecated API.
Minor point releases (2.0, 2.1, 2.2) is where Committers:
* May add API signatures
* May not modify API signatures
* May deprecate API.
Patch point releases (2.1.1, 2.1.2, 2.1.3) is where Committers:
* May not add API signatures
* May not modify API signatures
* May deprecate API.
Struts (2000-2006) in series 1.x has held to these rules except for the
last, which we never had point releases. The Apache Commons library follows
something very similar and as strict, and I believe is the
quality/trust/confidence needed for upgrading.
Paul
On Fri, Feb 22, 2008 at 9:09 AM, Brian Pontarelli <br...@pontarelli.com>
wrote:
> Piero Sartini wrote:
> > Am Freitag, 22. Februar 2008 00:05:53 schrieb Don Brown:
> >
> >> Yes, you are missing my original point #2 - "We need to be able to do
> >> "alpha" releases to get new, experimental features into the community
> >> for testing." I need a way to create an alpha release for 2.1 to hand
> >> off to our community for feedback, but if all releases require a
> >> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
> >>
> >> Public API changes take a while and lots of feedback to really get
> >> right, so going six months without a release is not acceptable, IMO.
> >>
> >
> > If these changes need feedback .. why not put them in alpha releases?
> 2.2
> > Alpha1, 2.2 Alpha2, etc
> >
> > For me, s.th. like this would be great:
> > A.B.C.D
> >
> > D -> Error fixing, security patches, etc
> > C -> new features, smaller api changes even incompatible ones
> > B -> big changes, large refactorings, new approaches, etc.
> > A -> Struts version
> >
> This would be sub-patch compatibility, which is fine and most tools
> currently or could easily support this. That would mean that 2.1.1.0 and
> 2.1.1.1 would be compatible, but 2.1.0 and 2.1.1 are not. Therefore, if
> your project depended on 2.1.1.0 and transitively depended on 2.1.0.0,
> the build would break, as it should.
>
> -bp
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Piero Sartini wrote:
> Am Freitag, 22. Februar 2008 00:05:53 schrieb Don Brown:
>
>> Yes, you are missing my original point #2 - "We need to be able to do
>> "alpha" releases to get new, experimental features into the community
>> for testing." I need a way to create an alpha release for 2.1 to hand
>> off to our community for feedback, but if all releases require a
>> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
>>
>> Public API changes take a while and lots of feedback to really get
>> right, so going six months without a release is not acceptable, IMO.
>>
>
> If these changes need feedback .. why not put them in alpha releases? 2.2
> Alpha1, 2.2 Alpha2, etc
>
> For me, s.th. like this would be great:
> A.B.C.D
>
> D -> Error fixing, security patches, etc
> C -> new features, smaller api changes even incompatible ones
> B -> big changes, large refactorings, new approaches, etc.
> A -> Struts version
>
This would be sub-patch compatibility, which is fine and most tools
currently or could easily support this. That would mean that 2.1.1.0 and
2.1.1.1 would be compatible, but 2.1.0 and 2.1.1 are not. Therefore, if
your project depended on 2.1.1.0 and transitively depended on 2.1.0.0,
the build would break, as it should.
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Piero Sartini <li...@pierosartini.de>.
Am Freitag, 22. Februar 2008 00:05:53 schrieb Don Brown:
> Yes, you are missing my original point #2 - "We need to be able to do
> "alpha" releases to get new, experimental features into the community
> for testing." I need a way to create an alpha release for 2.1 to hand
> off to our community for feedback, but if all releases require a
> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
>
> Public API changes take a while and lots of feedback to really get
> right, so going six months without a release is not acceptable, IMO.
If these changes need feedback .. why not put them in alpha releases? 2.2
Alpha1, 2.2 Alpha2, etc
For me, s.th. like this would be great:
A.B.C.D
D -> Error fixing, security patches, etc
C -> new features, smaller api changes even incompatible ones
B -> big changes, large refactorings, new approaches, etc.
A -> Struts version
Maybe you could drop the A - so we are at Struts2 1.1 instead of 2.1.1
Piero
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Jeromy Evans wrote:
> Hi Brian,
>
> I shared your frustration when I moved a plugin from 2.1.0 to 2.1.1.
> Initially I was taken-aback by the significance of the changes to the
> PackageConfig and ActionConfig that broke uses of MockConfiguration. I
> didn't expect such a large change between minor revisions and was
> disappointed there was no attempt to stay backwards compatible.
> HOWEVER, within a few minutes I'd seen the Builders and found the
> comments that backwards compatibility was broken to ensure
> immutability of the objects. It didn't take me long to get over it.
I had the same experience and moved forward with the convention plugin.
However, it doesn't mean that red flags didn't go up. Upgrading code is
something that can always be done. However, at some point things should
solidify so that Struts can be upgraded without upgrading everything
else and recompiling everything. This isn't about my experience, it is
about how this impacts everyone else out there. Transitive dependencies
are very tricky and we need to be cognizant of the fact that some folks
might not depend on Struts or the plugins directly.
>
> For me the problem is was one of communication:
> - I didn't know the change was coming because I generally don't follow
> XWork (I blame myself for not seeking release notes);
> - I didn't expect such a significant change between 2.1.0 -> 2.1.1,
> but as there hasn't been a GA release in the 2.1.x branch it's
> acceptable and known that each revision may be largely incompatible
> with the last. It's unreasonable to withhold such a change until 2.2
> as feedback is necessary, so within the existing configuration
> management framework it seems the correct practice was followed. Sure
> I'd prefer a numbering system matched my own, but the current one does
> work. Sure I'd have preferred some transitional arrangements, but the
> hard-change was technically justified.
In my case the issue was a not a matter of communication. It was a
matter of broken dependencies, runtime errors and managing two separate
codebases for SmartURLs and other projects depending on the version of
struts. I work with roughly 20-30 codebases all using different versions
of nearly everything and managing that can be a severe nightmare when
you consider these types of API changes.
> In the case of renaming interceptors and results, I think that
> migration was managed very well. It was introduced early,
> transitional arrangements put in place and it has been
> well-communicated.
True, however it still required that applications wanting to upgrade
required changes. It is still an API change. Again, just to re-iterate
the fact that I'm okay with API breakage, as long as it is managed and
allows tools to figure things out.
> In the case of removing support for EL in struts tags, I think that
> migration was managed badly from 2.0.9->2.0.11 and many users were
> adversely affected.
Yeah, that was painful for a lot of clients and applications I manage
and I still am considering a taglib fork that uses EL and deals well
with Object.
> With respect to Tools, the continuous build system is the *best* tool
> for checking if a contract through a public API has been broken iff
> there are test cases and/or a reference versions (eg. showcase) for
> each API. I do think its a reasonable assumption that a plugin built
> against, say, 2.0.6, will "by definition" execute with 2.0.11.
> However I would not expect that before a GA release of the branch, and
> I would never warrant that myself that if I released a plugin. I
> guess that's your fundamental expectation.
Agreed. That would be the way to manage some of the complexity. It would
also be the way to roll integration builds that users can consume.
> I do think there is a problem of communication in that:
> - there is no "reference" plugin that exercises what we're loosely
> calling the public APIs
> - the release notes are oriented towards users. There's no release
> notes for plugin developers
> - The plugin developers guide doesn't articulate what is in fact a
> public API
I agree that there are some communication problems, but they aren't
really all that major for me. Most of my frustration comes from not
having a convention that I can tell new developers, clients, etc. how
Struts is compatible across versions.
> With respect to dependency management, there was a specific problem in
> that bundled plugins generally referenced a specific struts 2 core
> version (eg. 2.0.6) rather than the parent ${pom.version}so they could
> build if the latest core API had changed. I believe that's been
> rectified, or perhaps it only applied in the non-bundled plugins I've
> examined.
That's very maven specific and often only useful for those folks
intimately using Maven and Struts. All the clients I work with use
Apache Ant and Savant for builds and a few use Ivy. Therefore,
transitive dependencies are managed through those systems, so we usually
do them by hand up front. However, there are a number of transitive
dependency cases that I've outlined in earlier emails where it would not
matter if the pom is correct.
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Jeromy Evans <je...@blueskyminds.com.au>.
Hi Brian,
I shared your frustration when I moved a plugin from 2.1.0 to 2.1.1.
Initially I was taken-aback by the significance of the changes to the
PackageConfig and ActionConfig that broke uses of MockConfiguration. I
didn't expect such a large change between minor revisions and was
disappointed there was no attempt to stay backwards compatible. HOWEVER,
within a few minutes I'd seen the Builders and found the comments that
backwards compatibility was broken to ensure immutability of the
objects. It didn't take me long to get over it.
For me the problem is was one of communication:
- I didn't know the change was coming because I generally don't follow
XWork (I blame myself for not seeking release notes);
- I didn't expect such a significant change between 2.1.0 -> 2.1.1, but
as there hasn't been a GA release in the 2.1.x branch it's acceptable
and known that each revision may be largely incompatible with the last.
It's unreasonable to withhold such a change until 2.2 as feedback is
necessary, so within the existing configuration management framework it
seems the correct practice was followed. Sure I'd prefer a numbering
system matched my own, but the current one does work. Sure I'd have
preferred some transitional arrangements, but the hard-change was
technically justified.
In the case of renaming interceptors and results, I think that migration
was managed very well. It was introduced early, transitional
arrangements put in place and it has been well-communicated.
In the case of removing support for EL in struts tags, I think that
migration was managed badly from 2.0.9->2.0.11 and many users were
adversely affected.
With respect to Tools, the continuous build system is the *best* tool
for checking if a contract through a public API has been broken iff
there are test cases and/or a reference versions (eg. showcase) for each
API. I do think its a reasonable assumption that a plugin built
against, say, 2.0.6, will "by definition" execute with 2.0.11. However
I would not expect that before a GA release of the branch, and I would
never warrant that myself that if I released a plugin. I guess that's
your fundamental expectation.
I do think there is a problem of communication in that:
- there is no "reference" plugin that exercises what we're loosely
calling the public APIs
- the release notes are oriented towards users. There's no release
notes for plugin developers
- The plugin developers guide doesn't articulate what is in fact a
public API
With respect to dependency management, there was a specific problem in
that bundled plugins generally referenced a specific struts 2 core
version (eg. 2.0.6) rather than the parent ${pom.version}so they could
build if the latest core API had changed. I believe that's been
rectified, or perhaps it only applied in the non-bundled plugins I've
examined.
cheers,
Jeromy Evans
Don Brown wrote:
> Yes, you are missing my original point #2 - "We need to be able to do
> "alpha" releases to get new, experimental features into the community
> for testing." I need a way to create an alpha release for 2.1 to hand
> off to our community for feedback, but if all releases require a
> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
>
> Public API changes take a while and lots of feedback to really get
> right, so going six months without a release is not acceptable, IMO.
>
> Don
>
> On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
>
>> Don Brown wrote:
>> > On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
>> >
>> >> > These two points, put together, will necessarily result in a 2.1.0
>> >> > release that is drastically different than 2.1.1. I just don't see
>> >> > any way around that.
>> >> >
>> >>
>> >> Tooling can solve this issue.
>> >>
>> >
>> > How? As I said, it is not possible for Struts releases to be
>> > compatible across patch versions. How will tooling solve this?
>> >
>>
>> I'm confused as to why it is not possible for them to be compatible.
>> Compatibility is part of software engineering and up to the developers.
>> Tools can perform static code analysis prior to releasing a patch
>> version and determine if APIs have changed. I would envision this type
>> of process:
>>
>> 1. Everyone tries their best not to bork 2.1.x
>> 2. The release manager for 2.1.2 (for example) runs the tool to check
>> public APIs against the 2.1.1 tag and trunk in SubVersion.
>> 3. If the tool passes or the errors seem acceptable to the release
>> manager, they do the release.
>> 4. If the tool finds errors and the errors look bad, release manager
>> halts release and tells developer that made said changes to fix them.
>>
>> Am I missing something?
>>
>>
>> -bp
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>> For additional commands, e-mail: dev-help@struts.apache.org
>>
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
> Before you start such a discussion, I would suggest that you take the time
> to look back, in the archives, through the several years worth of
> discussions in that got us to the point we're at today, so that you _fully_
> understand the context and the reasoning behind the scheme that we have now.
> I really, really don't want to rehash those discussions, because they are
> always very prolonged, they consume vast amounts of time, energy and
> enthusiasm, and they seriously eat into the real development effort because
> of that. I'd much prefer to see the team's effort go into making Struts the
> best that it can be rather than go off down that rat hole.
>
> The one tip I will give you before you head to the archives is that our
> process is basically the same as the ones used by HTTPD and Tomcat, two of
> the most long-standing projects in all of the ASF, so it's not something we
> made up off the top of our heads. It's been proven in the real world for
> more than a decade.
>
> All of that said, once you fully understand all of the history, and if you
> still feel you have a really compelling reason for the project to switch to
> another scheme, you are of course absolutely free to propose it. But do
> spend the time first, so that you realise what you are letting yourself -
> and the rest of us - in for, and expect to significantly slow down progress
> on the code until that discussion comes to closure.
>
I will have to drop off this discussion for the next few days to finish
up a project I'm working on, but before that I would like to respond to
folks so that I can still be active in the thread I started.
Martin, I've actually be involved in these discussion before and read up
on a number of them. I will certainly read the entire set when time
allows. However, regardless of that reading the scheme is still broken
and needs to be fixed. This is important to me because I am a maintainer
of a dependency management tool and where we are today is extremely
difficult to manage in these tools.
Furthermore, just because other projects do something doesn't make it
correct. HTTD is a full application not a library. Tomcat is also a full
application and not a library. Struts is a library and that means people
have compile and runtime dependencies on it in a much different manner.
In addition, I don't think I've ever seen Tomcat break API across a
minor release. This again comes back to developers understanding
compatibility.
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Martin Cooper <ma...@apache.org>.
On Thu, Feb 21, 2008 at 7:03 PM, Brian Pontarelli <br...@pontarelli.com>
wrote:
> Don Brown wrote:
> > Yes, you are missing my original point #2 - "We need to be able to do
> > "alpha" releases to get new, experimental features into the community
> > for testing." I need a way to create an alpha release for 2.1 to hand
> > off to our community for feedback, but if all releases require a
> > unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
> >
> > Public API changes take a while and lots of feedback to really get
> > right, so going six months without a release is not acceptable, IMO.
> >
> I think we will have to disagree on this point. From my perspective
> these things are mutually exclusive. You can make experimental new
> features and changes without breaking compatibility. It still comes down
> to being pragmatic about your changes and ensuring things don't break
> severely. However, I want to make it clear that I'm NOT advocating never
> breaking compatibility. I just want a versioning scheme that ensures
> tools can figure it out.
>
> As a separate question, why can't the scheme be changed for Struts 2
> specifically? I get a sense that everyone is saying, "don't even think
> about changing it because it will never happen." If something isn't
> working and there are better ways to handle things, isn't it our jobs as
> engineers to fix them?
Before you start such a discussion, I would suggest that you take the time
to look back, in the archives, through the several years worth of
discussions in that got us to the point we're at today, so that you _fully_
understand the context and the reasoning behind the scheme that we have now.
I really, really don't want to rehash those discussions, because they are
always very prolonged, they consume vast amounts of time, energy and
enthusiasm, and they seriously eat into the real development effort because
of that. I'd much prefer to see the team's effort go into making Struts the
best that it can be rather than go off down that rat hole.
The one tip I will give you before you head to the archives is that our
process is basically the same as the ones used by HTTPD and Tomcat, two of
the most long-standing projects in all of the ASF, so it's not something we
made up off the top of our heads. It's been proven in the real world for
more than a decade.
All of that said, once you fully understand all of the history, and if you
still feel you have a really compelling reason for the project to switch to
another scheme, you are of course absolutely free to propose it. But do
spend the time first, so that you realise what you are letting yourself -
and the rest of us - in for, and expect to significantly slow down progress
on the code until that discussion comes to closure.
--
Martin Cooper
>
> -bp
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Don Brown wrote:
> Yes, you are missing my original point #2 - "We need to be able to do
> "alpha" releases to get new, experimental features into the community
> for testing." I need a way to create an alpha release for 2.1 to hand
> off to our community for feedback, but if all releases require a
> unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
>
> Public API changes take a while and lots of feedback to really get
> right, so going six months without a release is not acceptable, IMO.
>
I think we will have to disagree on this point. From my perspective
these things are mutually exclusive. You can make experimental new
features and changes without breaking compatibility. It still comes down
to being pragmatic about your changes and ensuring things don't break
severely. However, I want to make it clear that I'm NOT advocating never
breaking compatibility. I just want a versioning scheme that ensures
tools can figure it out.
As a separate question, why can't the scheme be changed for Struts 2
specifically? I get a sense that everyone is saying, "don't even think
about changing it because it will never happen." If something isn't
working and there are better ways to handle things, isn't it our jobs as
engineers to fix them?
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
Yes, you are missing my original point #2 - "We need to be able to do
"alpha" releases to get new, experimental features into the community
for testing." I need a way to create an alpha release for 2.1 to hand
off to our community for feedback, but if all releases require a
unique patch version, I'm forced to create 2.1.1, 2.1.2, 2.1.3, etc.
Public API changes take a while and lots of feedback to really get
right, so going six months without a release is not acceptable, IMO.
Don
On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
> Don Brown wrote:
> > On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
> >
> >> > These two points, put together, will necessarily result in a 2.1.0
> >> > release that is drastically different than 2.1.1. I just don't see
> >> > any way around that.
> >> >
> >>
> >> Tooling can solve this issue.
> >>
> >
> > How? As I said, it is not possible for Struts releases to be
> > compatible across patch versions. How will tooling solve this?
> >
>
> I'm confused as to why it is not possible for them to be compatible.
> Compatibility is part of software engineering and up to the developers.
> Tools can perform static code analysis prior to releasing a patch
> version and determine if APIs have changed. I would envision this type
> of process:
>
> 1. Everyone tries their best not to bork 2.1.x
> 2. The release manager for 2.1.2 (for example) runs the tool to check
> public APIs against the 2.1.1 tag and trunk in SubVersion.
> 3. If the tool passes or the errors seem acceptable to the release
> manager, they do the release.
> 4. If the tool finds errors and the errors look bad, release manager
> halts release and tells developer that made said changes to fix them.
>
> Am I missing something?
>
>
> -bp
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Don Brown wrote:
> On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
>
>> > These two points, put together, will necessarily result in a 2.1.0
>> > release that is drastically different than 2.1.1. I just don't see
>> > any way around that.
>> >
>>
>> Tooling can solve this issue.
>>
>
> How? As I said, it is not possible for Struts releases to be
> compatible across patch versions. How will tooling solve this?
>
I'm confused as to why it is not possible for them to be compatible.
Compatibility is part of software engineering and up to the developers.
Tools can perform static code analysis prior to releasing a patch
version and determine if APIs have changed. I would envision this type
of process:
1. Everyone tries their best not to bork 2.1.x
2. The release manager for 2.1.2 (for example) runs the tool to check
public APIs against the 2.1.1 tag and trunk in SubVersion.
3. If the tool passes or the errors seem acceptable to the release
manager, they do the release.
4. If the tool finds errors and the errors look bad, release manager
halts release and tells developer that made said changes to fix them.
Am I missing something?
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
> > These two points, put together, will necessarily result in a 2.1.0
> > release that is drastically different than 2.1.1. I just don't see
> > any way around that.
> >
>
> Tooling can solve this issue.
How? As I said, it is not possible for Struts releases to be
compatible across patch versions. How will tooling solve this?
Don
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Don Brown wrote:
> Here are my two points:
> 1. Our current versioning scheme requires patch versions for all
> releases, regardless of quality
> 2. We need to be able to do "alpha" releases to get new, experimental
> features into the community for testing
>
> These two points, put together, will necessarily result in a 2.1.0
> release that is drastically different than 2.1.1. I just don't see
> any way around that.
>
Tooling can solve this issue.
> As for your other point about dependencies, well, that problem goes
> away once the convention plugin is bundled with Struts, because it
> will then have the same version number and will necessarily be
> compatibility with its counterparts in that release.
>
It doesn't go away because although it is bundled with struts, it is a
separate JAR and that means it is a separate dependency inside pom.xml,
project.xml, ivy.xml etc. The case I gave is real and folks have run
into already with smart-urls and will run into it with other plugins,
even those bundled with Struts.
> As for third-party plugins, yes, that is an issue, but I don't see how
> it is any different than any other library. My app depends on
> Velocity 1.5, but a library I use depends on Velocity 1.4, so problems
> could arise. We have this all the time in the projects I work on, so
> I don't see how Struts is unique here.
>
They won't arise if the tool (i.e. savant) knows how Struts is
compatible across versions. If we state that struts is ALWAYS compatible
across patch versions (ie 2.1.0 and 2.1.1) than the tool can correctly
pick the latest version. Or in the case below, it will produce an error
because 2.0.6 and 2.1.1 are not compatible. Let the tool do the heavy
lifting of managing all the dependencies including transitive. That's
what maven, ivy and savant are designed to do.
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
Here are my two points:
1. Our current versioning scheme requires patch versions for all
releases, regardless of quality
2. We need to be able to do "alpha" releases to get new, experimental
features into the community for testing
These two points, put together, will necessarily result in a 2.1.0
release that is drastically different than 2.1.1. I just don't see
any way around that.
As for your other point about dependencies, well, that problem goes
away once the convention plugin is bundled with Struts, because it
will then have the same version number and will necessarily be
compatibility with its counterparts in that release.
As for third-party plugins, yes, that is an issue, but I don't see how
it is any different than any other library. My app depends on
Velocity 1.5, but a library I use depends on Velocity 1.4, so problems
could arise. We have this all the time in the projects I work on, so
I don't see how Struts is unique here.
Don
On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
>
> Don Brown wrote:
> > Well said, and I completely agree. My original point is your point #1
> > just isn't possible with the current versioning scheme. Because every
> > release gets its own patch number, regardless of quality or API
> > changes, it can't be counted on, and really, I don't see any solution
> > other than creating a big matrix of releases for users to somehow
> > navigate the sea of releases to understand which are compatible with
> > the other.
> >
>
> I agree with you on that. It is difficult. However, it doesn't mean that
> a person or tool couldn't check the public APIs for changes prior to
> doing a release. The release would not ever occur and remain in
> -SNAPSHOT until those broken APIs are fixed.
>
>
> From the other thread:
>
> > I do agree we need to be much better about how much of our API we
> > expose to developers, but I think the question of public vs private
> > API goes beyond the Java semantics and into what a typical Struts user
> > will encounter. Unless you are a plugin or framework developer, it
> > would be very rare for you to be creating configuration objects, so
> > yes, while these are technically public, I'd certainly call them more
> > private than, say, the Action interface.
>
> It is actually more complex than I think you realize. Here is another dependency graph that reveals a really bad issue:
>
>
> Project A -> struts 2.0.6
>
> Project A -> library B
> Project A -> library C
>
> library B -> convention-plugin 2.0.6 -> struts 2.0.6
>
> library C -> struts 2.1.1
>
> This graph is broken because the build will decide that 2.1.1 is the latest and most correct version of Struts to use and put that in the classpath. However, the API changes in 2.1.1 break the convention plugin. BUT struts 2.1.1 doesn't depend on the convention plugin 2.1.1 and therefore the build is incapable of warning the user that things are broken and cannot manage this graph correctly.
>
> So, any public APIs need to be managed and when you introduce transitive dependencies, things get complex. Applications will break, even if they don't use those public APIs directly.
>
>
> -bp
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Don Brown wrote:
> Well said, and I completely agree. My original point is your point #1
> just isn't possible with the current versioning scheme. Because every
> release gets its own patch number, regardless of quality or API
> changes, it can't be counted on, and really, I don't see any solution
> other than creating a big matrix of releases for users to somehow
> navigate the sea of releases to understand which are compatible with
> the other.
>
I agree with you on that. It is difficult. However, it doesn't mean that
a person or tool couldn't check the public APIs for changes prior to
doing a release. The release would not ever occur and remain in
-SNAPSHOT until those broken APIs are fixed.
From the other thread:
> I do agree we need to be much better about how much of our API we
> expose to developers, but I think the question of public vs private
> API goes beyond the Java semantics and into what a typical Struts user
> will encounter. Unless you are a plugin or framework developer, it
> would be very rare for you to be creating configuration objects, so
> yes, while these are technically public, I'd certainly call them more
> private than, say, the Action interface.
It is actually more complex than I think you realize. Here is another dependency graph that reveals a really bad issue:
Project A -> struts 2.0.6
Project A -> library B
Project A -> library C
library B -> convention-plugin 2.0.6 -> struts 2.0.6
library C -> struts 2.1.1
This graph is broken because the build will decide that 2.1.1 is the latest and most correct version of Struts to use and put that in the classpath. However, the API changes in 2.1.1 break the convention plugin. BUT struts 2.1.1 doesn't depend on the convention plugin 2.1.1 and therefore the build is incapable of warning the user that things are broken and cannot manage this graph correctly.
So, any public APIs need to be managed and when you introduce transitive dependencies, things get complex. Applications will break, even if they don't use those public APIs directly.
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
Well said, and I completely agree. My original point is your point #1
just isn't possible with the current versioning scheme. Because every
release gets its own patch number, regardless of quality or API
changes, it can't be counted on, and really, I don't see any solution
other than creating a big matrix of releases for users to somehow
navigate the sea of releases to understand which are compatible with
the other.
Don
On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
<snip />
> 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: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Don Brown wrote:
> On 2/22/08, Brian Pontarelli <br...@pontarelli.com> 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: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
On 2/22/08, Brian Pontarelli <br...@pontarelli.com> 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.
> 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?
Don
>
>
> -bp
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
Don Brown wrote:
> But don't you see, if we used the more traditional 1.0-alpha-1 ->
> 1.0-beta-1 -> 1.0-rc-1 -> 1.0 then we could produce releases that
> drastically changed the API within a single version. As it is now,
> there could very well be huge changes from 1.0 to 1.0.1 because every
> release gets its own numeric version number, regardless of quality.
>
You can always make changes that break APIs. This can happen using any
versioning scheme. It isn't about whether or not you CAN do it. It is
whether or not you SHOULD do it.
In most projects, the version numbers are used only to signify
compatibility and uniqueness. Whether or not it uses alpha/beta/etc. or
just patch versions doesn't matter. If you use good dependency
management tools they will handle compatibility across any versioning
scheme, whether it is minor, patch, major, whatever.
> I agree the changes in 2.1 are very significant, so much so that they
> necessitate multiple alpha releases to get feedback from the
> community. Currently, there is no way to do that without releasing
> 2.1.0 -> 2.1.1 -> 2.1.2.
>
You are talking about something different than what I'm talking about.
You are talking about version numbers and I'm talking about compatibility.
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.
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.
-bp
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
But don't you see, if we used the more traditional 1.0-alpha-1 ->
1.0-beta-1 -> 1.0-rc-1 -> 1.0 then we could produce releases that
drastically changed the API within a single version. As it is now,
there could very well be huge changes from 1.0 to 1.0.1 because every
release gets its own numeric version number, regardless of quality.
I agree the changes in 2.1 are very significant, so much so that they
necessitate multiple alpha releases to get feedback from the
community. Currently, there is no way to do that without releasing
2.1.0 -> 2.1.1 -> 2.1.2.
Again, the versioning discussion has happened many times before, and
individual numeric releases is how the community has decided to run
Struts, and that's fine. Then, the question becomes how we can better
educate our users on what to expect.
Don
On 2/22/08, Brian Pontarelli <br...@pontarelli.com> wrote:
>
> From my perspective the issue isn't education, it is compatibility at
> the code level. Making changes that severely break plugins and
> applications needs to be reserved for major releases. Here are two
> examples that had severe impacts:
>
> - Making XWork objects immutable with the builder pattern
>
> This change broke a number of plugins because that API is public and
> reducing visibility or removing methods is not a compatible change.
>
> - Changing the names of the interceptors in struts.xml
>
> This change broke all applications that had custom interceptor
> chains. This is a higher level of public API in the configuration files
> and renaming methods or ids is not a compatible change.
>
>
> These types of changes seem to be the largest issue with the versioning
> of Struts 2.
>
>
> -bp
>
>
>
>
> Don Brown wrote:
> > Yeah, the way Struts does versions kinda breaks this. You could see
> > very major changes between 2.1.0 and 2.1.1 because neither made GA.
> > Once a GA release has been made in a series, however, the normal rules
> > apply. It is beating a dead horse to say I never liked the Struts
> > versioning system, so moving forward, how can we better educate our
> > users on how things work?
> >
> > Don
> >
> > On 2/21/08, Brian Pontarelli <br...@pontarelli.com> wrote:
> >
> >> >> The API has yet to be solidified and there are a few things that I'd
> >> >> still like to discuss and possibly change in that regard. My main goal
> >> >> is to ensure backwards compatibility in the convention plugin API.
> >> >>
> >> >
> >> > My thinking is like this:
> >> > upgrading from [today's convention-plugin] to [final convention-plugin]
> >> > will be much easier than upgrading from [codebehind] to the [final
> >> > convention-plugin].
> >> >
> >> True. The changes will probably not impact most applications, but will
> >> be API changes and not compatible.
> >>
> >>
> >> >> Furthermore, I think we should all start thinking about when the "true"
> >> >> stable release of XWork and Struts2 will be.
> >> >>
> >> >
> >> > Isn't a GA release meant to be a "true stable release"?
> >> > I think to know what you want to say, but I am still somewhat confused about
> >> > why releases in s2 are working the way they do.
> >> >
> >> It depends on your versioning system. I prefer for all minor numbers
> >> (2.x) to be compatible and all major numbers (x.0) to be incompatible
> >> for the API perspective. I also feel that patches numbers (2.1.x) should
> >> not add or subtract features. Therefore, the schema I use GAs don't
> >> measure compatibility, the version numbers to. In my world you release
> >> GAs for majors, minors and patches when they are final. If the release
> >> isn't final, it uses a signifier like A, B, RC, M. For example,
> >> 2.1.1-RC1 would be the first release candidate and 2.1.1 would be the GA
> >> final release. Struts versioning is much different though.
> >>
> >> >> I think it makes sense to
> >> >> target the next release and jump up to 2.5 or some number to indicate
> >> >> stable APIs. This would include a number of API clean-ups, OGNL
> >> >> replacement and a few other things that will severely break plugins and
> >> >> applications. After that release, API changes should be compatible so
> >> >> that plugins and applications can be upgraded without requiring
> >> >> re-compiling.
> >> >>
> >> >
> >> > I am quite sure there will rise another list with new issues that should be
> >> > resolved before a "true" release in some time...
> >> > In my oppinion, API stability is nothing that comes with reaching some feature
> >> > set or project milestone. This would imply stopping innovation at that point.
> >> > For me, API stability needs to be some kind of project goal or philosophy -
> >> > which needs to be enforced by defining commonly accepted rules.
> >> >
> >> I agree for the most part, but also use version numbers to imply API
> >> freeze and compatibility. Innovation and API compatibility are not
> >> mutually exclusive. Folks just have to understand what they can and
> >> cannot do to APIs. For example, you cannot remove any methods or classes
> >> otherwise, it isn't compatible. You can add new methods and classes and
> >> this implies the ability to innovate. Deprecation can also be used
> >> correctly (not like the JDK) to handle API changes between major versions.
> >>
> >> > But my impression is that this is no (important) goal for s2, and I can hardly
> >> > imagine that it will be one day just because it gets to a point where
> >> > _today's_ most wanted features are implemented.
> >> >
> >> Not yet, but I want to make it one. I think since the plugin system
> >> allows developers access to APIs that were at one point internal, it
> >> changes things quite a bit. These APIs are now public and need to be
> >> stabilized at some point. Otherwise we will end up having developers who
> >> are constantly battling with upgrading plugins and applications and get
> >> turned off by Struts.
> >>
> >> > But maybe this is worth a new thread...
> >> >
> >> Agreed ;)
> >>
> >>
> >> -bp
> >>
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> >> For additional commands, e-mail: dev-help@struts.apache.org
> >>
> >>
> >>
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> > For additional commands, e-mail: dev-help@struts.apache.org
> >
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Brian Pontarelli <br...@pontarelli.com>.
From my perspective the issue isn't education, it is compatibility at
the code level. Making changes that severely break plugins and
applications needs to be reserved for major releases. Here are two
examples that had severe impacts:
- Making XWork objects immutable with the builder pattern
This change broke a number of plugins because that API is public and
reducing visibility or removing methods is not a compatible change.
- Changing the names of the interceptors in struts.xml
This change broke all applications that had custom interceptor
chains. This is a higher level of public API in the configuration files
and renaming methods or ids is not a compatible change.
These types of changes seem to be the largest issue with the versioning
of Struts 2.
-bp
Don Brown wrote:
> Yeah, the way Struts does versions kinda breaks this. You could see
> very major changes between 2.1.0 and 2.1.1 because neither made GA.
> Once a GA release has been made in a series, however, the normal rules
> apply. It is beating a dead horse to say I never liked the Struts
> versioning system, so moving forward, how can we better educate our
> users on how things work?
>
> Don
>
> On 2/21/08, Brian Pontarelli <br...@pontarelli.com> wrote:
>
>> >> The API has yet to be solidified and there are a few things that I'd
>> >> still like to discuss and possibly change in that regard. My main goal
>> >> is to ensure backwards compatibility in the convention plugin API.
>> >>
>> >
>> > My thinking is like this:
>> > upgrading from [today's convention-plugin] to [final convention-plugin]
>> > will be much easier than upgrading from [codebehind] to the [final
>> > convention-plugin].
>> >
>> True. The changes will probably not impact most applications, but will
>> be API changes and not compatible.
>>
>>
>> >> Furthermore, I think we should all start thinking about when the "true"
>> >> stable release of XWork and Struts2 will be.
>> >>
>> >
>> > Isn't a GA release meant to be a "true stable release"?
>> > I think to know what you want to say, but I am still somewhat confused about
>> > why releases in s2 are working the way they do.
>> >
>> It depends on your versioning system. I prefer for all minor numbers
>> (2.x) to be compatible and all major numbers (x.0) to be incompatible
>> for the API perspective. I also feel that patches numbers (2.1.x) should
>> not add or subtract features. Therefore, the schema I use GAs don't
>> measure compatibility, the version numbers to. In my world you release
>> GAs for majors, minors and patches when they are final. If the release
>> isn't final, it uses a signifier like A, B, RC, M. For example,
>> 2.1.1-RC1 would be the first release candidate and 2.1.1 would be the GA
>> final release. Struts versioning is much different though.
>>
>> >> I think it makes sense to
>> >> target the next release and jump up to 2.5 or some number to indicate
>> >> stable APIs. This would include a number of API clean-ups, OGNL
>> >> replacement and a few other things that will severely break plugins and
>> >> applications. After that release, API changes should be compatible so
>> >> that plugins and applications can be upgraded without requiring
>> >> re-compiling.
>> >>
>> >
>> > I am quite sure there will rise another list with new issues that should be
>> > resolved before a "true" release in some time...
>> > In my oppinion, API stability is nothing that comes with reaching some feature
>> > set or project milestone. This would imply stopping innovation at that point.
>> > For me, API stability needs to be some kind of project goal or philosophy -
>> > which needs to be enforced by defining commonly accepted rules.
>> >
>> I agree for the most part, but also use version numbers to imply API
>> freeze and compatibility. Innovation and API compatibility are not
>> mutually exclusive. Folks just have to understand what they can and
>> cannot do to APIs. For example, you cannot remove any methods or classes
>> otherwise, it isn't compatible. You can add new methods and classes and
>> this implies the ability to innovate. Deprecation can also be used
>> correctly (not like the JDK) to handle API changes between major versions.
>>
>> > But my impression is that this is no (important) goal for s2, and I can hardly
>> > imagine that it will be one day just because it gets to a point where
>> > _today's_ most wanted features are implemented.
>> >
>> Not yet, but I want to make it one. I think since the plugin system
>> allows developers access to APIs that were at one point internal, it
>> changes things quite a bit. These APIs are now public and need to be
>> stabilized at some point. Otherwise we will end up having developers who
>> are constantly battling with upgrading plugins and applications and get
>> turned off by Struts.
>>
>> > But maybe this is worth a new thread...
>> >
>> Agreed ;)
>>
>>
>> -bp
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>> For additional commands, e-mail: dev-help@struts.apache.org
>>
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: API Compatibility
Posted by Don Brown <mr...@twdata.org>.
Yeah, the way Struts does versions kinda breaks this. You could see
very major changes between 2.1.0 and 2.1.1 because neither made GA.
Once a GA release has been made in a series, however, the normal rules
apply. It is beating a dead horse to say I never liked the Struts
versioning system, so moving forward, how can we better educate our
users on how things work?
Don
On 2/21/08, Brian Pontarelli <br...@pontarelli.com> wrote:
>
> >> The API has yet to be solidified and there are a few things that I'd
> >> still like to discuss and possibly change in that regard. My main goal
> >> is to ensure backwards compatibility in the convention plugin API.
> >>
> >
> > My thinking is like this:
> > upgrading from [today's convention-plugin] to [final convention-plugin]
> > will be much easier than upgrading from [codebehind] to the [final
> > convention-plugin].
> >
> True. The changes will probably not impact most applications, but will
> be API changes and not compatible.
>
>
> >> Furthermore, I think we should all start thinking about when the "true"
> >> stable release of XWork and Struts2 will be.
> >>
> >
> > Isn't a GA release meant to be a "true stable release"?
> > I think to know what you want to say, but I am still somewhat confused about
> > why releases in s2 are working the way they do.
> >
> It depends on your versioning system. I prefer for all minor numbers
> (2.x) to be compatible and all major numbers (x.0) to be incompatible
> for the API perspective. I also feel that patches numbers (2.1.x) should
> not add or subtract features. Therefore, the schema I use GAs don't
> measure compatibility, the version numbers to. In my world you release
> GAs for majors, minors and patches when they are final. If the release
> isn't final, it uses a signifier like A, B, RC, M. For example,
> 2.1.1-RC1 would be the first release candidate and 2.1.1 would be the GA
> final release. Struts versioning is much different though.
>
> >> I think it makes sense to
> >> target the next release and jump up to 2.5 or some number to indicate
> >> stable APIs. This would include a number of API clean-ups, OGNL
> >> replacement and a few other things that will severely break plugins and
> >> applications. After that release, API changes should be compatible so
> >> that plugins and applications can be upgraded without requiring
> >> re-compiling.
> >>
> >
> > I am quite sure there will rise another list with new issues that should be
> > resolved before a "true" release in some time...
> > In my oppinion, API stability is nothing that comes with reaching some feature
> > set or project milestone. This would imply stopping innovation at that point.
> > For me, API stability needs to be some kind of project goal or philosophy -
> > which needs to be enforced by defining commonly accepted rules.
> >
> I agree for the most part, but also use version numbers to imply API
> freeze and compatibility. Innovation and API compatibility are not
> mutually exclusive. Folks just have to understand what they can and
> cannot do to APIs. For example, you cannot remove any methods or classes
> otherwise, it isn't compatible. You can add new methods and classes and
> this implies the ability to innovate. Deprecation can also be used
> correctly (not like the JDK) to handle API changes between major versions.
>
> > But my impression is that this is no (important) goal for s2, and I can hardly
> > imagine that it will be one day just because it gets to a point where
> > _today's_ most wanted features are implemented.
> >
> Not yet, but I want to make it one. I think since the plugin system
> allows developers access to APIs that were at one point internal, it
> changes things quite a bit. These APIs are now public and need to be
> stabilized at some point. Otherwise we will end up having developers who
> are constantly battling with upgrading plugins and applications and get
> turned off by Struts.
>
> > But maybe this is worth a new thread...
> >
> Agreed ;)
>
>
> -bp
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org