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
_______________________________________________
Product-Developers mailing list
[email protected]
http://lists.plone.org/mailman/listinfo/product-developers
