This is a temporary place to note decisions. The idea is to later integrate them into the Zope Toolkit documentation, but we need a quick way to note decisions first.
ZMI related code shall not be part of the Zope Toolkit, and we shall strive to remove it.
If zope.deferredimport is used in a package merely to avoid the use of from imports, then instead we will use from imports to get rid of this dependency.
Files used to support the old ZPKG system such as DEPENDENCIES.cfg can be safely removed from packages.
So-called “ZCML-slugs” which were intended to be symlinked into a special slugs directory in a Zope installation are not in use anymore. They should be removed. Typically they look like zope.foo-configure.zcml.
we are going to work at getting rid of the zope.app.testing extra by distributing its facilities into individual zope.* packages. Hopefully we can get a clear consensus on this one from the people who object to the general policy.
if you think a new “extra” dependency is needed in a Zope Toolkit package, and you’re not just moving stuff between packages but actually developing new code, bring it up on zope-dev so we can at least consider alternatives. Perhaps a better home can be found for this code.
We can consider removing extra dependencies for particular Zope Toolkit packages in order to make the dependency graph easier to reason about. We will do this on a case by case basis though.
In namespace package’s __init__.py we have been using the following boilerplate code:
try:
import pkg_resources
pkg_resources.declare_namespace(__name__)
except ImportError:
import pkgutil
__path__ = pkgutil.extend_path(__path__, __name__)
Since setuptools is a dependency of our packages anyway, we can instead do the following:
__import__('pkg_resources').declare_namespace(__name__)
Feel free to use that and also feel free to simplify existing __init__.py modules. Just make sure setuptools is a declared dependency of the package.
Moving code around as part of dependency refactoring is worth a feature release (x.y as opposed to x.y.z version number) for the affected packages. Changing an import to make use of a new package that came out of such refactoring is also worth a feature release.
If a package A starts to rely on new features in dependency B, that is worth a feature release of package A.
The version requirements in setup.py should specify only API compatibility. They should not specify a dependency on bug fixes; that’s the domain of the KGS.
Therefore in a setup.py you are allowed to write this in setup.py:
bar >= x.y
I.e. relying on a newer feature release of package bar.
but not this:
bar >= x.y.z
I.e. you’re not allowed to rely on a newer bugfix release of package bar.
Elaboration: Imagine package foo that depends on package bar. If you make changes in foo so that it starts to rely on changes in bar that are only introduced in a feature release of bar (bar version x.y or bar version x), you should update the setup.py of foo to state this dependency with a requirement like this:
bar >= x.y
This is only relevant to feature releases. If there is a bugfix release of bar you should not write a dependency like bar >= x.y.z.
This is a compromise in the interests of both flexibility and giving hints to people who use our packages. We’ll see how it goes.
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.
When code moves to a new location to import it from (in the same or another package), use a from foo import bar statement, with a #BBB comment to indicate the import is only there to support backwards compatibility.
In the CHANGES.txt of a package, state that an import location got deprecated and where the new location is (making this a feature release, not a bugfix release).
Reasons:
The open issues will be moved to the launchpad blueprints and launchpad answers. The blueprint specifications will be stored in the ZTK documentation and linked to (each blueprint will be a separate document).
As a general direction we’d like to separate out the XML-RPC related code and FTP-related code into seperate packages that aren’t depended on by the rest of the toolkit. This makes it possible for developers to use the toolkit without worrying about XML-RPC or FTP.
To make it easy for developers to identify which packages are in the ZTK, as they are sometimes working in isolation, a package that is maintained by the Zope Toolkit project should have the following text in its setup.py file just under the copyright header:
##############################################################################
# This package is developed by the Zope Toolkit project, documented here:
# http://docs.zope.org/zopetoolkit
# When developing and releasing this package, please follow the documented
# Zope Toolkit policies as described by this documentation.
##############################################################################
When a package is removed from the ZTK this header should be removed from its setup.py as well.
There was a discussion about whether the version in setup.py should be set to 0 instead of the next expected version. There was a discussion and the majority of the steering group was against this change - the ZTK release policy remains the same for the ZTK.
The mailing list threads discusses various pros and cons:
https://mail.zope.org/pipermail/zope-dev/2009-September/037725.html
https://mail.zope.org/pipermail/zope-dev/2009-September/037735.html
We want to encourage narrative documentation for packages (doctested or not). Even though we do not require that this documentation is executable (doctested), we do prefer a project setup so that it easy to support executable documentation as well, in cooperation with tools like manuel. The bobo documentation is an example of such a setup. We should document this better.