[Zope-dev] my take on ZCML's includeOverrides

[Chris McDonough]

On Tue, 2010-12-07 at 14:27 -0500, Chris McDonough wrote:

> > > [13:48] <mcdonc> override is exactly the wrong phrase to use in the name
> > > of this directive
> > > [13:51] <mcdonc> what it boils down to is that you never, ever really
> > > want to use includeOverrides except in your rootmost zcml file
> > > [13:51] <mcdonc> and probably not even there
> > > [13:51] <mcdonc> because you can get the same effect by typing the
> > > directives there by hand
> > 
> > Why would you want to type the directives by hand?
> 
> I *think* I'm of the opinion that libraries (or even "reusable
> applications") probably shouldn't need to use includeOverrides.  You
> might disagree.  I'd actually like to hear your take on that, because
> I'm only about 90% confident about that. ;-)  I realize that not every
> application knows whether it's going to be reused or not, but, even so,
> it's always an option to cutnpaste the topmost ZCML from that
> application into a new file and disuse the old one.
> 
> But if you take for granted the idea that libraries shouldn't use
> "includeOverrides", the place that it is actually potentially useful is
> in the "deployment" ZCML file (the topmost ZCML file that includes other
> ZCML from libraries and other application packages).  But in this
> scenario, I already "own" the topmost ZCML file, and since it's
> deployment-specific, there's no sense in breaking out the included stuff
> into a separate file, because no one else will ever reuse it.  It's all
> deployment-specific policy.

So, arguing with myself about that:

[14:31] <mcdonc> so i can see exactly one use case for includeOverrides
so far
[14:31] <mcdonc> that's that you have an existing application which
doesnt have its zcml nicely factored
[14:31] <mcdonc> and you're afraid (for whatever reason) to just
cutpaste it into a new app
[14:31] <mcdonc> and you want to create a new package
[14:32] <mcdonc> that includes the other application's zcml then
override bits of it
[14:32] <mcdonc> you could do that by doing
[14:32] <mcdonc> <include package="oldapp"/>
[14:32] <mcdonc> <view ../>
[14:32] <mcdonc> <view ..>
[14:32] <mcdonc> or you could do
[14:32] <mcdonc> <include package="oldapp"/>
[14:33] <mcdonc> <includeOverrides package="newapp.views"
filename="configure.zcml"/>
[14:33] <mcdonc> either would have exactly the same effect

So yes, I see what you were getting at in your last mail.

But I think we might be wise to draw some lines around this
reuse-of-an-application pattern, at least conventionally.

My take on application reuse is this: as soon as you've assumed control
of top-level configuration via a "newapp" overrides package, you've more
or less chosen to use "oldapp" as a library rather than as
just-an-application (NB: oldapp and newapp are names I mention above in
the example of includeOverride, representing an application that wants
to be reused as "oldapp" and a package created by an overriding user as
"newapp").

This sort of usage is a bit weird, because usually you depend on a
plain-old-Python library to have a relatively stable API.  But in the
application-reuse example, often the original "oldapp" author has
provided no such stability assurances with respect to how he uses ZCML.
In such a case, you're always going to be depending on implementation
details.

When you punt to reusing oldapp's toplevel ZCML, it's because you don't
want to track changes to oldapp, but you still want to get the benefit
of being able to override some of its policy in newapp.  I think this is
pretty much impossible in general.  Although your newapp overrides *may*
continue to work across oldapp updates, if oldapp provided no promise of
stability, you'll still need to track its changes.

It would be much better if the oldapp author provided instructions about
how to best reuse his application as a library.  Those instructions
probably wouldn't instruct customizers to reuse his top-level "example"
ZCML configuration, but might imply reusing some other ZCML files that
include configuration unlikely to need to be overridden.  Or he might
ship part of "oldapp" as a "true" library that has a bit of ZCML in it
for reuse by integrators, but distribute another package that represents
a deployable configuration of "oldapp" in a separate package.  Or
something.

I dunno, hard topic.

- C