On 2/23/06, Sean Schofield <[EMAIL PROTECTED]> wrote:
It might be useful to subdivide the general term "component APIs" a bit ... there are different considerations for different pieces of this puzzle (and I think this might be what Adam is driving at when he talks about public vs. non-public APIs).
* Components -- JavaBean classes that *will* be used on occasion
in applications (either casting in an event handler so you can call
a component specific method, or when defining the property type
for a component accessed via a "binding" attribute). Since these
classes are accessed directly in applications, normal rules about
API evolution should apply.
* Tag Handlers -- The tag classes are not manipulated by an application developer
directly, but they *are* used indirectly (by virtue of using the corresponding
JSP custom tags). Therefore, removing an attribute would be bad, but
adding a new one (as long as it's not required) should be ok.
* Renderers -- The actual implementation classses should *not* be
accessed directly by applications ... it should all be indirect via
registration. Therefore, it seems reasonable to have more flexibility
in making changes here -- UNLESS we want to provide renderer
base classes that are designed for easy subclassing for component
developers. So, there's probably two sub-families here.
* Converters and Validators -- probably more like components than like
tag handlers or renderers ... normal evolution rules are appropriate.
We also need to be aware that many of the potential users for this source are not technically equipped to actually take advantage of this ... they want (or are required by their IT managers) to use stock released binaries.
In Shale, I'm trying an experiment to declare API stability by package, and also to define who the target audience is (app developers versus people wanting to extend the framework). Something in the same spirit might be relevant here:
http://struts.apache.org/struts-shale/api-stability.html
Hmm ... that's certainly not the approach we took with Struts. We have generally been pretty anal about breaking backwards compatibility, and this is one of the things IMHO that has made it popular, on an orthogonal dimension to its technical characteristics.
Not being explicit about API stability promises is definitely a problem ... and we should definitely solve it (after we've decided which APIs are stable and which are not, of course :-).
Same comments as above ... users of open source software are not necessarily any more capable (or more allowed) to deal with non-release-binary versions. Yes, there's a tradeoff between the pace of innovation and the churn of users, but as MyFaces becomes more popular it needs to pay serious attention to the latter issue, not just the former.
> I don't understand this; don't the component APIs matter? Do
> you truly believe that MyFaces should feel free to make any change
> at any time?
The component API's matter but I don't hold the components to the same
standard as I would a language or framework. I think its unrealistic
for a user to assume that an entire suite of components won't have an
API change even years after release. I want to reiterrate how we
should not take these changes lightly. We should try our best to
limit them.
It might be useful to subdivide the general term "component APIs" a bit ... there are different considerations for different pieces of this puzzle (and I think this might be what Adam is driving at when he talks about public vs. non-public APIs).
* Components -- JavaBean classes that *will* be used on occasion
in applications (either casting in an event handler so you can call
a component specific method, or when defining the property type
for a component accessed via a "binding" attribute). Since these
classes are accessed directly in applications, normal rules about
API evolution should apply.
* Tag Handlers -- The tag classes are not manipulated by an application developer
directly, but they *are* used indirectly (by virtue of using the corresponding
JSP custom tags). Therefore, removing an attribute would be bad, but
adding a new one (as long as it's not required) should be ok.
* Renderers -- The actual implementation classses should *not* be
accessed directly by applications ... it should all be indirect via
registration. Therefore, it seems reasonable to have more flexibility
in making changes here -- UNLESS we want to provide renderer
base classes that are designed for easy subclassing for component
developers. So, there's probably two sub-families here.
* Converters and Validators -- probably more like components than like
tag handlers or renderers ... normal evolution rules are appropriate.
> It's not fair to say "no one's forcing them to upgrade": if you provide
> three features and ten bug fixes they need, they are forced to upgrade.
We will work with the users to help them upgrade and provide advance
warning when such a change is envisioned. We even give them a chance
to object and convince us not to make the change. We also make the
source available so that they can build their own version of the
component without the changes they want. Most of these luxuries are
not available to the typical purchaser of OTS software.
We also need to be aware that many of the potential users for this source are not technically equipped to actually take advantage of this ... they want (or are required by their IT managers) to use stock released binaries.
> I agree that *at this point* in MyFaces, it's critical to fix
> APIs to do the right thing. But at a certain point, if you
> want people to use your software, you need to give them
> some level of confidence that their code's not going to break
> every time they upgrade. And sometimes that means
> saying "nice idea, but it'll have to wait 'til 2.0." Or providing
> an uglier implementation, like an ExtendedTreeModel subinterface
> that adds the additional methods without breaking existing
> users.
If we follow a conservative approach to changing interfaces then I
think our users will understand and accept that approach. Again, this
should be rare case but not completely rigid like Sun is with their
languages or specs (for understandable reasons.)
In Shale, I'm trying an experiment to declare API stability by package, and also to define who the target audience is (app developers versus people wanting to extend the framework). Something in the same spirit might be relevant here:
http://struts.apache.org/struts-shale/api-stability.html
> I think "there are no customers except for us" is sophistry
> that dodges the issue. Surely you want others to use
> your software? And you care when they complain?
> If not, why have a [email protected] list?
Of course we want users to user our software. But if 90% of the
"customers" would benefit from an interface change and the other 10%
object strongly, the majority wins. Particularly if the 90% are the
people doing all of the work (whether is the coding, documentation or
support.) The 10% have no standing because they did nothing but use
the free software and tech support. Obviously we want to avoid this
situation, but if it comes down to that, that's the way I see it.
Ideally everyone is happy but I think you would agree that we won't be
able to please everyone - no matter which approach we take.
Hmm ... that's certainly not the approach we took with Struts. We have generally been pretty anal about breaking backwards compatibility, and this is one of the things IMHO that has made it popular, on an orthogonal dimension to its technical characteristics.
> If it isn't rock solid, it's not a public API, and should be
> documented as such. I totally agree that priorities need
> to be set! One consequence of "not enough time" is
> admitting that some APIs really can't be made truly public,
> because they're not rock solid. So make that statement
> explicit instead of leaving users in the dark.
Who is documenting it as such? I don't recall reading the words "rock
solid" or "guaranteed not to change" anywhere in our documentation.
Maybe we could put a disclaimer on our website or something but I
think our users are trusting that we will do the right thing and break
backwards compatability only as a last resort.
The commons (now shared) stuff is pretty volatile and I would agree we
need to be clear that this stuff is for internal use only. If we do
ever have a commons project to be used outside of MyFaces that really
does need to be a rigid API.
Not being explicit about API stability promises is definitely a problem ... and we should definitely solve it (after we've decided which APIs are stable and which are not, of course :-).
> Yep for #3 - but I really think that the issue of solidifying public APIs
> is extremely important, and we can't just say "this is open
> source, so it doesn't matter". Software is software; reusable
> libraries are reusable libraries; how they're developed doesn't
> mean we should lower our expectations.
I think the fact that it is open source makes a difference. Open
source is more fluid then commercial software development. Our users
are also generally more sophisticated. They like to work with the
cutting edge, hence the popularity of nightly builds. They know the
risks. We can get more components out the door faster if we don't
obsess over every detail of the interface before releasing. At the
same time, we do have the sandbox where components mature before
release. So nothing is done in haste. I think this is a nice
balance.
Same comments as above ... users of open source software are not necessarily any more capable (or more allowed) to deal with non-release-binary versions. Yes, there's a tradeoff between the pace of innovation and the churn of users, but as MyFaces becomes more popular it needs to pay serious attention to the latter issue, not just the former.
> -- Adam
Sean
Craig
