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

[Chris McDonough]

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.

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

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

> I've used includeOverrides in cases where:
> 
> 1. I want to use 2 high-level components, one of which
>     customizes the other, or in which
> 
> 2. I wanted to organize overrides in various ways where I
>     don't want to put everything in a root (or high-level file).
> 
> Of course, you can sometimes get the same effect in other ways.
> For example, if one high-level component overrides another, then
> the overriding component can just include the overridden one.
> 
> Jim
>