faassen at startifact
May 13, 2009, 10:36 AM
Post #1 of 1
(351 views)
Permalink
|
|
reusability markers in our documentation
|
|
Hi there,
In the "ZTK futures" thread Chris McDonough pointed out that right now
we don't signal which packages are easily reusable outside of the Zope
Toolkit and which packages aren't, and need a great knowledge of the way
the Zope Toolkit works and a large amount of installed packages.
In order to increase our focus on reusable packages that stand on their
own, and to reduce confusion by the outside world, we should signal
clearly which packages should be considered by the broader community,
and more importantly, which packages they can safely ignore.
I've therefore created the following guideline in the Zope Toolkit
decisions document:
Some Zope Toolkit packages are quite reusable without having to buy
into the rest of the Zope Toolkit. Others aren't reusable at all
without pulling in a huge chunk of the Zope Toolkit; they depend on
many assumptions.
We should communicate this clearly to potential users. As a first
step, we will make sure these notifications are available on the
PyPI pages. We will do this by adding a message about reusability to
the long_description (which gets displayed on PyPI). Typically this
is done by modifying the package's README.txt or
``src/zope/../README.txt`` doctest.
The following text should be used for reusable packages::
*This package is intended to be independently reusable in any Python
project. It is maintained by the* `Zope Toolkit project
<http://docs.zope.org/zopetoolkit/>`_.
The following text should be used for packages that are *not*
easily reusable::
*This package is at present not reusable without depending on a
large chunk of the Zope Toolkit and its assumptions. It is
maintained by the* `Zope Toolkit project
<http://docs.zope.org/zopetoolkit/>`_.
At the time of writing, most of our packages will be marked as *not*
reusable. Only packages at the roots of our dependency tree that
have a clear purpose and some documentation (such as
``zope.interface`` and ``zope.component``) should be marked as
reusable. We will slowly start to build up from there.
Help is needed to mark these packages. As a safe assumption, all
zope.app.* packages should be marked as not reusable. It's a simple
matter of going to the setup.py, seeing what file ends up being the
start of long_description (typically README.txt or something like that)
and modifying it with the marker text.
I've marked zope.component, zope.interface and zope.schema as
"reusable". That doesn't mean their documentation shouldn't be improved
to support this; it should. But nevertheless it's pretty doable to reuse
them today. We have more such packages; in case of any doubt about the
status, please bring it up in discussions here.
I've marked zope.app.publication as not reusable already.
Volunteers to help mark the other packages?
Regards,
Martijn
_______________________________________________
Zope-Dev maillist - Zope-Dev [at] zope
http://mail.zope.org/mailman/listinfo/zope-dev
** No cross posts or HTML encoding! **
(Related lists -
http://mail.zope.org/mailman/listinfo/zope-announce
http://mail.zope.org/mailman/listinfo/zope )
|
