Proposal: Determining packages which are in the ZTK
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 This is from a note I sent yesterday to the ZTK steering group (Martijn, Christian, Jim, Stephan), proposing criteria for removing packages from the ZTK. Martijn has already updated the docs to reflect some of the criteria: I figured I would throw the rest out for discussion: - - If a ZTK package isn't used by at least Zope2 and Grok, it probably isn't getting the love needed to stay at an appropriate quality level to meet the ZTK goals. Given that the Zope2 developers have as an explicit goal removing dependencies on *any* zope.app.* package, I obviously believe that such packages should not be part of the ZTK. - - Any package which doesn't have real narrative documentation checked into its 'docs' subdirectory, or a commitment from a maintainer to create such docs, should be on probation. - - Any package which depends on a zope.* package which is *not* part of the ZTK should itself be removed from the ZTK. - - As a corollary, any package which depends on any other "probationary" package is automatically probationary itself. - - (A little more speculative) Any package which doesn't have one or more clearly-identified maintainers should be probationary. - - Packages which remain in the probationary status for a given period (three months? six?) should be removed from the ZTK. The overall goal here is to keep the ZTK as coherent as possible, and avoid "bitrot" by focusing on the packages which are in active use by more than one project. Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFKs6zm+gerLs4ltQ4RAuBrAKCmtecUClk+EmaNvyuXS+A6seGLpwCfSKtS Kx/kzSRzZ5r28MahjjXX9Zo= =b4sb -----END PGP SIGNATURE-----
On Sep 18, 2009, at 11:53 AM, Tres Seaver wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
This is from a note I sent yesterday to the ZTK steering group (Martijn, Christian, Jim, Stephan), proposing criteria for removing packages from the ZTK. Martijn has already updated the docs to reflect some of the criteria: I figured I would throw the rest out for discussion:
- - If a ZTK package isn't used by at least Zope2 and Grok, it probably isn't getting the love needed to stay at an appropriate quality level to meet the ZTK goals. Given that the Zope2 developers have as an explicit goal removing dependencies on *any* zope.app.* package, I obviously believe that such packages should not be part of the ZTK.
- - Any package which doesn't have real narrative documentation checked into its 'docs' subdirectory, or a commitment from a maintainer to create such docs, should be on probation.
- - Any package which depends on a zope.* package which is *not* part of the ZTK should itself be removed from the ZTK.
- - As a corollary, any package which depends on any other "probationary" package is automatically probationary itself.
- - (A little more speculative) Any package which doesn't have one or more clearly-identified maintainers should be probationary.
- - Packages which remain in the probationary status for a given period (three months? six?) should be removed from the ZTK.
The overall goal here is to keep the ZTK as coherent as possible, and avoid "bitrot" by focusing on the packages which are in active use by more than one project.
Sounds interesting. Do you happen to have a list of packages that would be affected by these rules? Gary
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Gary Poster wrote:
Sounds interesting.
Do you happen to have a list of packages that would be affected by these rules?
Sure: all the zope.app packages. They have effectively been in "probationary" status for a while now; I'm proposing to remove them completely from the ZTK. Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFKs7NP+gerLs4ltQ4RAnzaAJ0e/oLpeO6/TcBEggPjO03DoDNazgCgj0z5 ws36yQbTkTJ3rHobw1szIqg= =Wy/f -----END PGP SIGNATURE-----
On Fri, Sep 18, 2009 at 6:20 PM, Tres Seaver <tseaver@palladion.com> wrote:
Sure: all the zope.app packages. They have effectively been in "probationary" status for a while now; I'm proposing to remove them completely from the ZTK.
I'd like to leave any zope.app.* package in the under-review section as long as one is a dependency of a ZTK package. This includes testing dependencies. We need to care and maintain those packages as long as we depend on them. Otherwise we could move them to the dependency section, so we'd make sure to have a complete working set. Take for example zope.traversing [1] which has a major bunch of test dependencies. I'd like the process to be: first refactor the tests, then drop the dependency. Hanno [1] http://svn.zope.org/zope.traversing/trunk/setup.py?view=markup
On Fri, Sep 18, 2009 at 11:53 AM, Tres Seaver <tseaver@palladion.com> wrote:
- - Any package which depends on a zope.* package which is *not* part of the ZTK should itself be removed from the ZTK.
+1
- - As a corollary, any package which depends on any other "probationary" package is automatically probationary itself.
+0
- - (A little more speculative) Any package which doesn't have one or more clearly-identified maintainers should be probationary.
-0 -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
On 2009-09-18, Tres Seaver <tseaver@palladion.com> wrote:
- - Any package which doesn't have real narrative documentation checked into its 'docs' subdirectory, or a commitment from a maintainer to create such docs, should be on probation.
This sounds like - It really has to be the docs/ subdir (which keeps it hidden from for instance omelette). - It should not be a doctest. /me wants to make sure Reinout -- Reinout van Rees - reinout@vanrees.org - http://reinout.vanrees.org Software developer at http://www.thehealthagency.com "Military engineers build missiles. Civil engineers build targets"
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Reinout van Rees wrote:
On 2009-09-18, Tres Seaver <tseaver@palladion.com> wrote:
- - Any package which doesn't have real narrative documentation checked into its 'docs' subdirectory, or a commitment from a maintainer to create such docs, should be on probation.
This sounds like
- It really has to be the docs/ subdir (which keeps it hidden from for instance omelette).
I am arguing for a convention of Sphinx-like stuff in the "top-level" sdit tree, parallel to the source, rather than intermingled with the source.
- It should not be a doctest.
I meant to write that the docs must be primarily narrative, rather than a set of doctest "bricks" stitched together with thin pseudo-prose "mortar". Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFKuVLU+gerLs4ltQ4RAgITAKDUvlU3TDOvNFLaaUOaa7z+3SyqXwCdHvc/ +qlzFTf5TpsOLJavqhvuYL4= =YTR6 -----END PGP SIGNATURE-----
Hey, Generally I believe that these rules if strictly applied wouldn't result in a usable ZTK. Hanno already mentions the testing dependencies, which we've barely started analyzing. Documentation in 'docs' would disqualify just about any package (and Reinout brings up a few objections). A number of thoughts: * even without radically pruning the ZTK particular subsets of the ZTK are becoming a lot more useful than when we started, due the dependency refactoring. This refactoring is ongoing. * we need some stability for those apps that already are built on top of Zope 3. These will still be using zope.app* packages for some time. Right now we can test lots of breakages of zope.app* packages by using the ZTK compattests. If we removed them from the ZTK soon, we'd need an equivalent testing infrastructure for an expanded ZTK, and management policy will be harder. I think we could translate these rules from "not be part of the ZTK" to goals for the ZTK packages: - we should aim for ZTK packages to be used by Zope 3 apps, Zope 2 and Grok. The code in the ZTK should be *used*. - ZTK packages should have narrative documentation. We should actively work to create such narrative documentation. - We strive to remove zope.app.* packages from the ZTK or its dependencies. This can sometimes be done directly but can also be done by refactoring dependencies, factoring out useful code away from ZMI code, etc. The implementation of these goals should be debated for individual packages. Of course this exposes us that the risk that nothing gets done and the ZTK remains as it is forever. A more aggressive set of rules might be seen as a way to force us to do something. I'm not sure whether that's a problem we need to solve: we do have people actively working on improving the ZTK, and this has been ongoing work for most of the year so far. I'm also not sure whether the solution of aggressive removal would work: if we don't do anything, would we really start threatening people with aggressive removal? Regards, Martijn
On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen <faassen@startifact.com> wrote:
Documentation in 'docs' would disqualify just about any package (and Reinout brings up a few objections).
I definitively want the option of making documentation executable. Manuel makes it a lot easier to make good documentation executable. I think the bobo documentation are a pretty good example of narrative documentation. They are tested using manuel. Interestingly, the parts I didn't initially test with manuel turned out to have lots of typos. :) Jim -- Jim Fulton
Jim Fulton wrote:
On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen <faassen@startifact.com> wrote:
Documentation in 'docs' would disqualify just about any package (and Reinout brings up a few objections).
I definitively want the option of making documentation executable.
Manuel makes it a lot easier to make good documentation executable. I think the bobo documentation are a pretty good example of narrative documentation. They are tested using manuel. Interestingly, the parts I didn't initially test with manuel turned out to have lots of typos. :)
I agree we should continue to explore executable documentation and there is a lot of potential for manuel and a good example in the bobo documentation. At the same time, I wouldn't want "we want executable documentation" to be a roadblock for documentation writers. Setting up executable documentation can be quite hard. If we can get people to write narrative non-executable documentation at all we should support them fully. So, I'd be against any "you can't contribute documentation unless it's executable" rule. The value of narrative documentation is tremendous, automatically checked or not. Hopefully there are also iterative ways to get from non-executable to executable documentation. Regards, Martijn
On Sep 21, 2009, at 18:47 , Martijn Faassen wrote:
So, I'd be against any "you can't contribute documentation unless it's executable" rule. The value of narrative documentation is tremendous, automatically checked or not. Hopefully there are also iterative ways to get from non-executable to executable documentation.
+1 jens
On Mon, Sep 21, 2009 at 12:47 PM, Martijn Faassen <faassen@startifact.com> wrote:
Jim Fulton wrote:
On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen <faassen@startifact.com> wrote:
Documentation in 'docs' would disqualify just about any package (and Reinout brings up a few objections).
I definitively want the option of making documentation executable.
...
So, I'd be against any "you can't contribute documentation unless it's executable" rule. The value of narrative documentation is tremendous, automatically checked or not. Hopefully there are also iterative ways to get from non-executable to executable documentation.
All I said was that I wanted the option of executable documentation. In particular, I don't want to mandate a source organization that makes this harder. Jim -- Jim Fulton
Jim Fulton wrote:
On Mon, Sep 21, 2009 at 12:47 PM, Martijn Faassen <faassen@startifact.com> wrote:
Jim Fulton wrote:
On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen <faassen@startifact.com> wrote:
Documentation in 'docs' would disqualify just about any package (and Reinout brings up a few objections). I definitively want the option of making documentation executable.
...
So, I'd be against any "you can't contribute documentation unless it's executable" rule. The value of narrative documentation is tremendous, automatically checked or not. Hopefully there are also iterative ways to get from non-executable to executable documentation.
All I said was that I wanted the option of executable documentation. In particular, I don't want to mandate a source organization that makes this harder.
Just making sure we are all on the same page. I agree we shouldn't make this harder. We should look into documenting the approach bobo uses in the ZTK documentation so people have some ideas on how to approach this. I've added a note about this to the ZTK decisions document for now. Regards, Martijn
On Mon, Sep 21, 2009 at 1:52 PM, Martijn Faassen <faassen@startifact.com> wrote:
I agree we shouldn't make this harder. We should look into documenting the approach bobo uses in the ZTK documentation so people have some ideas on how to approach this.
The Manuel docs themselves are also good examples of using Manuel: Rendered as HTML at http://packages.python.org/manuel/ Source at http://svn.zope.org/*checkout*/manuel/trunk/src/index.txt -- Benji York Senior Software Engineer Zope Corporation
On 2009-9-21 17:19, Martijn Faassen wrote:
Hey,
Generally I believe that these rules if strictly applied wouldn't result in a usable ZTK. Hanno already mentions the testing dependencies, which we've barely started analyzing. Documentation in 'docs' would disqualify just about any package (and Reinout brings up a few objections).
A number of thoughts:
* even without radically pruning the ZTK particular subsets of the ZTK are becoming a lot more useful than when we started, due the dependency refactoring. This refactoring is ongoing.
* we need some stability for those apps that already are built on top of Zope 3. These will still be using zope.app* packages for some time. Right now we can test lots of breakages of zope.app* packages by using the ZTK compattests. If we removed them from the ZTK soon, we'd need an equivalent testing infrastructure for an expanded ZTK, and management policy will be harder.
I think we could translate these rules from "not be part of the ZTK" to goals for the ZTK packages:
- we should aim for ZTK packages to be used by Zope 3 apps, Zope 2 and Grok. The code in the ZTK should be *used*.
- ZTK packages should have narrative documentation. We should actively work to create such narrative documentation.
How do you define narrative documentation? Do you consider z3c.form to have narrative documentation for example? Wichert. -- Wichert Akkerman <wichert@wiggy.net> It is simple to make things. http://www.wiggy.net/ It is hard to make things simple.
participants (10)
-
Benji York -
Fred Drake -
Gary Poster -
Hanno Schlichting -
Jens Vagelpohl -
Jim Fulton -
Martijn Faassen -
Reinout van Rees -
Tres Seaver -
Wichert Akkerman