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

[Jim Fulton]

On Tue, Dec 7, 2010 at 2:27 PM, Chris McDonough <chrism at plope.com> wrote:
> On Tue, 2010-12-07 at 14:08 -0500, Jim Fulton wrote:
>> On Tue, Dec 7, 2010 at 1:57 PM, Chris McDonough <chrism at plope.com> wrote:
>> > Independent of my previous call for discussion about ZCML conflict
>> > resolution, I'm cutting and pasting my side of a discussion about the
>> > ZCML "includeOverrides" directive from an IRC chat, because it may come
>> > in useful for folks grappling with its behavior.  There's not really any
>> > human-consumable docs about it.
>> >
>> > If I've made any mistakes, please let me know.
>> >
>> > [13:42] <mcdonc> so ftr, i've found that ZCML's includeOverrides and
>> > include to do (at least on one vector) exactly the opposite of what you
>> > might expect them to do
>> > [13:42] <mcdonc> "includeOverrides" is a poor name
>> > [13:42] <mcdonc> what it does is to emulate the behavior of inlining
>> > stuff into the file you use it from
>> > [13:43] <mcdonc> when you use includeOverrides it's as if you typed all
>> > the directives in the included file into the file you're including from
>> > [13:43] <mcdonc> otoh, "include" doesnt behave like this
>> > [13:44] <mcdonc> you can actually define the same directive in three
>> > files
>> > [13:44] <mcdonc> configure.zcml, one.zcml, and two.zcml
>> > [13:44] <mcdonc> and if you use "include" from configure.zcml of one and
>> > two
>> > [13:44] <mcdonc> there will be no conflict
>> > [13:45] <mcdonc> this is because non-conflicting "rootmost" directives
>> > win
>> > [13:45] <mcdonc> otoh, if you use includeOverrides of one and two from
>> > configure.zcml
>> > [13:45] <mcdonc> all three will conflict
>> > [13:45] <mcdonc> because its as if you typed them all in configure.zcml
>> > by hand
>> > [13:45] <mcdonc> and that means there are three conflicting rootmost
>> > directives
>> > [13:46] <mcdonc> if you mentally substitute "inline" for
>> > "includeOverrides" it makes a little more sense
>>
>> Maybe.  It described the mechanism better, but includeOverrides conveys the
>> intent. <shrug>
>
> Sorry, not a criticism, just a personal observation.

No problem.  Your observation is valid.

> I assume I'm not wrong about the behavior I describe above?

I don't think so.

>> > [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. ;-)

By now you've probably seen my other post where I said I think
we've taken comparability too far. :)  I should have noted there
that I was talking about "configrability" in terms of selective overriding.

If something is going to be configurable, by which I mean overridable,
then I think includeOverrides or something like it is pretty valuable.

>  I realize that not every
> application knows whether it's going to be reused or not,

Not only that, YAGNI says it should be written from the start
as if it isn't, until it is. :) or more importantly, it shouldn't be written
to have it's parts overridden until a compelling reason has been
found to do so.

> 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.

Yeah, just like you can reuse Python code by copying it.
It's usually better to reuse by reference if possible.

> But if you take for granted the idea that libraries shouldn't use
> "includeOverrides",

Unless the library is built on some other library.  Even then,
include may be a better option, but there is still overriding going on.

> 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).

In practice, I haven't found this to be a single file, but that's
probably beside the point.

> 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.

This is like saying that a main program that uses libraries shouldn't be broken
into subprograms.

Jim

-- 
Jim Fulton