Mailing List Archive: Zope: Dev

Proposal: Determining packages which are in the ZTK

Index | Next | Previous | View Threaded

tseaver at palladion

Sep 18, 2009, 8:53 AM

Post #1 of 15 (1510 views)
Permalink

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 [at] palladion
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-----

_______________________________________________
Zope-Dev maillist - Zope-Dev [at] zope
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 )

gary.poster at gmail

Sep 18, 2009, 9:02 AM

Post #2 of 15 (1468 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

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 [at] zope
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 )

fdrake at gmail

Sep 18, 2009, 9:09 AM

Post #3 of 15 (1466 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

On Fri, Sep 18, 2009 at 11:53 AM, Tres Seaver <tseaver [at] palladion> 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 [at] zope
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 )

tseaver at palladion

Sep 18, 2009, 9:20 AM

Post #4 of 15 (1470 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

-----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 [at] palladion
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-----

_______________________________________________
Zope-Dev maillist - Zope-Dev [at] zope
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 )

hanno at hannosch

Sep 18, 2009, 10:08 AM

Post #5 of 15 (1464 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

On Fri, Sep 18, 2009 at 6:20 PM, Tres Seaver <tseaver [at] palladion> 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 [at] zope
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 )

reinout at vanrees

Sep 21, 2009, 12:32 AM

Post #6 of 15 (1449 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

On 2009-09-18, Tres Seaver <tseaver [at] palladion> 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 [at] vanrees - http://reinout.vanrees.org
Software developer at http://www.thehealthagency.com
"Military engineers build missiles. Civil engineers build targets"

_______________________________________________
Zope-Dev maillist - Zope-Dev [at] zope
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 )

faassen at startifact

Sep 21, 2009, 8:19 AM

Post #7 of 15 (1434 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

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 [at] zope
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 )

jim at zope

Sep 21, 2009, 9:17 AM

Post #8 of 15 (1430 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen
<faassen [at] startifact> 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 [at] zope
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 )

faassen at startifact

Sep 21, 2009, 9:47 AM

Post #9 of 15 (1438 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

Jim Fulton wrote:
> On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen
> <faassen [at] startifact> 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 [at] zope
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 )

jens at dataflake

Sep 21, 2009, 9:53 AM

Post #10 of 15 (1439 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

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

Attachments:

smime.p7s (4.70 KB)

jim at zope

Sep 21, 2009, 10:28 AM

Post #11 of 15 (1440 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

On Mon, Sep 21, 2009 at 12:47 PM, Martijn Faassen
<faassen [at] startifact> wrote:
> Jim Fulton wrote:
>> On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen
>> <faassen [at] startifact> 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 [at] zope
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 )

faassen at startifact

Sep 21, 2009, 10:52 AM

Post #12 of 15 (1432 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

Jim Fulton wrote:
> On Mon, Sep 21, 2009 at 12:47 PM, Martijn Faassen
> <faassen [at] startifact> wrote:
>> Jim Fulton wrote:
>>> On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen
>>> <faassen [at] startifact> 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 [at] zope
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 )

benji at zope

Sep 21, 2009, 10:58 AM

Post #13 of 15 (1437 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

On Mon, Sep 21, 2009 at 1:52 PM, Martijn Faassen <faassen [at] startifact> 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 [at] zope
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 )

wichert at wiggy

Sep 22, 2009, 1:45 AM

Post #14 of 15 (1405 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

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 [at] wiggy> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.
_______________________________________________
Zope-Dev maillist - Zope-Dev [at] zope
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 )

tseaver at palladion

Sep 22, 2009, 3:42 PM

Post #15 of 15 (1397 views)
Permalink

Re: Proposal: Determining packages which are in the ZTK [In reply to]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Reinout van Rees wrote:
> On 2009-09-18, Tres Seaver <tseaver [at] palladion> 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 [at] palladion
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-----

_______________________________________________
Zope-Dev maillist - Zope-Dev [at] zope
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 )

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads