Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
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 wich...@wiggy.net It is simple to make things. http://www.wiggy.net/ It is hard to make things simple. ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Reinout van Rees wrote: On 2009-09-18, Tres Seaver tsea...@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 tsea...@palladion.com Palladion Software Excellence by Designhttp://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- ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
On 2009-09-18, Tres Seaver tsea...@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 - rein...@vanrees.org - http://reinout.vanrees.org Software developer at http://www.thehealthagency.com Military engineers build missiles. Civil engineers build targets ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen faas...@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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
Jim Fulton wrote: On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen faas...@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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
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 smime.p7s Description: S/MIME cryptographic signature ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
On Mon, Sep 21, 2009 at 12:47 PM, Martijn Faassen faas...@startifact.com wrote: Jim Fulton wrote: On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen faas...@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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
Jim Fulton wrote: On Mon, Sep 21, 2009 at 12:47 PM, Martijn Faassen faas...@startifact.com wrote: Jim Fulton wrote: On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen faas...@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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
On Mon, Sep 21, 2009 at 1:52 PM, Martijn Faassen faas...@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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
[Zope-dev] 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 tsea...@palladion.com Palladion Software Excellence by Designhttp://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- ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
On Fri, Sep 18, 2009 at 11:53 AM, Tres Seaver tsea...@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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
-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 tsea...@palladion.com Palladion Software Excellence by Designhttp://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- ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Proposal: Determining packages which are in the ZTK
On Fri, Sep 18, 2009 at 6:20 PM, Tres Seaver tsea...@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 ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
