[Product-Developers] Re: ordering fields with schemaextender

Martin Aspeli optilude at gmx.net
Wed Jan 2 23:18:44 UTC 2008


Wichert Akkerman wrote:
> Previously Héctor Velarde wrote:
>> Wichert Akkerman wrote:
>>> schemaextender fully documents its adapters in their interface
>>> definition. For this case see ISchemaModifier
>> well, in fact schemaextender fully documented that on README.txt and I 
>> could had found it, if you hadn't erase it ;-)
> 
> Indeed, Martin just mailed me about that as well. I rewrote the README for a
> reason: as a testsuite it was incomplete and slow, and I found it very hard
> to understand as documentation if you did not already know exactly what it
> did and how things worked. A problem with doctests is that you need to
> insert a lot of extra fluff that is not interesting for human readers but
> which is needed to run the code as a test. This README suffered a lot from
> that.

In the case of this particular case, I'm not sure I agree. I spent a lot 
of time making it readable and understandable. The "fluff" is definitely 
fluff in terms of test coverage, but not in terms of setting out 
realistic use cases and making the usage understandable. Hector's 
experiences attest to that. He had problems understanding how the schema 
extender would work with vocabularies and defaults. That was in the old 
README (and I kept telling him to read it, not knowing it was gone :-)), 
but is not documented anymore.

> I added simple unittests to atse that have a better test coverage and run
> many many times faster than the old doctest. I also did my best to make the
> README as simple to understand as possible.

It's understandable, but it's incomplete. It doesn't cover schema 
modification, vocabularies or defaults.

Also, the old test was written to deal with issues that were only 
discoverable at runtime (e.g. template rendering) which caused breakage 
in earlier versions. I didn't want to add the testbrowser bit, but had 
to in order to avoid regressions around some bugs that we didn't find 
with mock-based testing, but which surfaced with real use cases. Since 
archetypes.schemaextender is a fairly invasive integration package, and 
since AT itself has so much weirdness at that level, I think it's hugely 
important to have integration tests for it, not just mock-based unit tests.

> I did not go into some of the
> details such as the schema modifier since those are not going to be
> important for 99% of the users and the interface definition has a decent
> description for them.

I don't think that's true. The modifier fields will be useful for a lot 
of people (e.g. for re-ordering), even if it's dangerous and thus 
discouraged by the interface design.

> If I had more time to spent on it I would have added
> those with some short examples to the README as well, but even without that
> I strongly feel that the new README is an improvement over the old one.

I think there's room for many things here:

  - A short readme in the package root and cheese shop page that 
explains the basics

  - A doctest that demonstrates usage in some detail

  - An integration test that proves this works end-to-end (with testbrowser)

  - Fast and methodical unit tests that cover the edge case permutations

To that end, I've re-added my README.txt as a "usage.txt" file (it still 
works, virtually unmodified, which is good news). It does still use the 
PloneSite layer and PloneTestCase, but that's contained to a single 
file, so you don't need to run this most of the time.

Does that work for you?

Martin

-- 
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book





More information about the Product-Developers mailing list