<!DOCTYPE debiandoc SYSTEM>

<debiandoc><book>
    <titlepag>
      <title>Debian Zope Policy</title>
      <author>
	<name>Matthias Klose</name>
	<email>doko@ubuntu.com</email>
      </author>
      <author>
	<name>Luca - De Whiskey's - De Vitis</name>
	<email>luca@debian.org</email>
      </author>
      <version>version 0.2</version>
      <abstract>
            This document aims to provide a set of rules for the packaging of
            <em>Zope application server</em> and its components within the Debian
            distribution. It's dervived from the Debian Zope Policy version 0.1.2,
            written by Luca - De Whiskey's - De Vitis (luca@debian.org).
        </abstract>
      <copyright>
	<copyrightsummary>
                Copyright &copy; 2003 Software in the Public Interest
            </copyrightsummary>
	<p>
                This manual is free software; you can redistribute it and/or
                modify it under the terms of the GNU General Public License
                as published by the Free Software Foundation; either version
                2 of the License, or (at your option) any later version.
            </p>
	<p>
                This is distributed in the hope that it will be useful, but
                WITHOUT ANY WARRANTY; without even the implied warranty of
                MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
                the GNU General Public License for more details.
            </p>
	<p>
                A copy of the GNU General Public License is available as
                <file>/usr/share/common-licences/GPL</file> in the Debian GNU/Linux
                distribution or on the World Wide Web at
                <url id="http://www.gnu.org/copyleft/gpl.html" name="The GNU Public Licence">.
            </p>
	<p>
                You can also obtain it by writing to the
                Free Software Foundation, Inc., 59 Temple Place - Suite 330,
                Boston, MA 02111-1307, USA.
            </p>
      </copyright>
    </titlepag>
    <toc detail="sect1">
    <chapt id="naming_conventions">
      <heading>Nameing convention</heading>
      <p>
            In the following sections, will use these convention:
            <taglist>
	  <tag><em>Zope</em></tag>
	  <item>
	    <p>
                        Will refer to the Zope application server as described
                        by <httpsite>http://www.zope.org</httpsite>.
                    </p>
	  </item>
                <tag><em>Zope Package</em></tag>
                <item>
                    <p>
                        Will refer to any software that extends the
                        capabilities of <em>Zope</em>, like <em>ZEO</em>
                        or <em>ZODB</em>.
                    </p>
                </item>
                <tag><em>Zope Product</em></tag>
                <item>
                    <p>
                        Will refer to any software that extends the range
                        of available objects for <em>Zope</em>, like
                        <em>ParsedXML</em>.
                    </p>
                </item>
                <tag><package>zope</package></tag>
                <item>
                    <p>
                        Will refer to the Debian package for <em>Zope</em>.
                    </p>
                </item>
                <tag><package>zope-<var>foo</var></package></tag>
                <item>
                    <p>
                        Will refer to the Debian package for a generic
                        <tt>foo</tt> <em>Zope Package</em> or <em>Zope
                        Product</em>.
                    </p>
                </item>
                <tag><em>ZPL</em></tag>
                <item>
                    <p>
                        Will refer to <strong>Zope Public License</strong>:
                        occasionally it may be followed by a version number
                        <var>V</var> (i.e. <em>ZPL-<var>V</var></em>).
                    </p>
                </item>
                <tag><em>FHS</em></tag>
                <item>
                    <p>
                        Will refer to <strong>Filesystem Hierarchy
                        Standard</strong> as documented in the
                        <url id="file:///usr/share/doc/debian-policy/fhs" name="Debian Policy">
                    </p>
                </item>
            </taglist>
        </p>
    </chapt>
    <chapt id="packages_names">
        <heading>Package names</heading>
        <sect id="main_package">
            <heading>Main package</heading>
            <p>
                <package>zope</package> package shall provide a complete,
                stand-alone distribution of <em>Zope</em>, suitable for
                <em>deployment</em> of <em>Zope</em> components and
                applications. <package>zope</package> will also include any
                <em>ZPL-<var>V</var></em> to be of use for reference by related
                components or applications
                <footnote>
                    <p>
                        Since we may not ask for the inclusion of any
                        <em>ZPL-<var>V</var></em> under
                        <prgn>common-licenses</prgn>, we may use
                        <file>/usr/share/doc/zope</file> instead.
                    </p>
                </footnote>.
            </p>
        </sect>
        <sect id="main_dev_package">
            <heading>Main development package</heading>
            <p>
                The package named <package>zope-dev</package> will provide the
                complete set of development files originally included in
                <em>Zope</em> and useful tools to help building Debian package
                for <em>Zope</em> components.
            </p>
        </sect>
        <sect id="products_and_packages">
            <heading><em>Zope Packages</em> and <em>Zope Products</em></heading>
            <p>
                Every Debian source package that intends to provide either
                a <em>Zope Package</em> or <em>Zope Product</em> named
                <tt>foo</tt>, should build the
                <package>zope-<var>foo</var></package> Debian package.
            </p>
        </sect>
        <sect id="other_packages">
            <heading>Other Debian packages</heading>
            <p>
                Debian packages for softwares simply related to <em>Zope</em>
                may use different name convention (i.e.
                <url id="http://packages.debian.org/zopeedit" name="zopeedit">).
            </p>
        </sect>
    </chapt>
    <chapt id="zope-foo">
        <heading><package>zope-<var>foo</var></package> package</heading>
        <sect id="zope-foo_paths">
            <heading>Paths</heading>
            <p>
                Any <package>zope-<var>foo</var></package> package should use the
                following paths or file guidelines:
                <taglist>
                    <tag><file>/usr/lib/zope</file></tag>
                    <item>
                        <p>
                            This is the home for <em>Zope</em> software. Any
                            <em>Zope Package</em> or <em>Zope Product</em>,
                            must be installed under an appropriate
                            subdirectory in order to work.
                        </p>
                    </item>
                    <tag><file>/usr/lib/zope/import</file></tag>
                    <item>
                        <p>
                            Import files (i.e. those files that usually have
                            <file>.zexp</file> extension) must installed under
                            this directory. Administrators may provide
                            symbolic links to desired files on a per-instance
                            base.
                        </p>
                    </item>
                    <tag><file>/usr/lib/zope/Extensions</file></tag>
                    <item>
                        <p>
                            Python extensin scripts must be installed under
                            this directory. Administrators may provide
                            symbolic links to desired files on a per-instance
                            base.
                        </p>
                    </item>
                    <tag><file>tests</file> directory</tag>
                    <item>
                        <p>
                            Debian package
                            <package>zope-<var>foo</var></package> may not
                            provide any <file>tests</file> directory
                            <footnote>
                                <p>
                                    See <url id="file:///usr/share/doc/zope/UNITTEST.txt.gz" name="UNITTEST.txt.gz">.
                                </p>
                            </footnote>
                            <footnote>
                                <p>
                                    There are many ways we can handle this:
                                    <list>
                                        <item><p>
                                            We may simply include
                                            <file>tests/</file> directory in
                                            <package>zope-<var>foo</var></package>
                                            package.
                                        </p></item>
                                        <item><p>
                                            We may build a
                                            <package>zope-<var>foo</var>-tests</package>
                                            that provides the
                                            <file>tests/</file> directory only.
                                        </p></item>
                                        <item><p>
                                            We may build a
                                            <package>zope-<var>foo</var>-debug</package>
                                            that <tt>Provides</tt>,
                                            <tt>Conflicts</tt> and
                                            <tt>Replace</tt>
                                            <package>zope-<var>foo</var></package>
                                        </p></item>
                                    </list>
                                </p>
                            </footnote>.
                        </p>
                    </item>
                </taglist>
            </p>
        </sect>
        <sect id="zope-foo_copyright">
            <heading>Notable files</heading>
            <p>
                <taglist>
                    <tag><file>/usr/share/doc/zope-<var>foo</var>/copyright</file></tag>
                    <item>
                        <p>
                            Debian package
                            <package>zope-<var>foo</var></package> may not
                            include any <em>ZPL-<var>V</var></em>; it may
                            simply refer to the license provided by the
                            <package>zope</package> package in the
                            <file>/usr/share/doc/zope/ZPL-<var>V</var></file>
                            file
                            <footnote>
                                <p>
                                    This would surely decrease the disk space used by the
                                    installation of several Debian packages of Zope
                                    Components. 
                                </p>
                            </footnote>.
                            The <file>copyright</file> file in source Debian
                            package may look like the following
                            <footnote>
                                <p>
                                    I would replace this with an example file
                                    as soon as possible.
                                </p>
                            </footnote>:
                            <example>
This is the Debian package of Zope <var>foo</var> component.

This package was put together by <var>Debian Developer</var> <var>&lt;account@debian.org&gt;</var>,
from sources obtained from:

  <var>protocol</var>://<var>site</var>/<var>path</var>

Author: <var>Upstream Author(s)</var> <var>&lt;mail@upstream.address&gt;</var>

Copyright:

This software is distributed under the term of the Zope Public License version <var>V</var>.
Please, refer to /usr/share/doc/zope/ZPL-<var>V</var>
                            </example>
                        </p>
                    </item>
                </taglist>
            </p>
        </sect>
        <sect id="configuring_zope-foo">
            <heading>Configuration and pre-configuration</heading>
            <p>
                As you should know, <em>Zope</em> need to be restarted to let each new
                component to be used, but <package>zope-<var>foo</var></package>
                should not ask any question to administrators about this
                issue
                <footnote>
                    <p>
                        For reference, read the reports on Bug
                        <url id="http://bugs.debian.org/134516" name="#134516"> and
                        <url id="http://bugs.debian.org/167033" name="#167033">, or the
                        <url id="http://lists.debian.org/debian-python/2002/debian-python-200211/msg00019.html" name="[zope] New features of the zope package 2.5.1-2.5">
                        thread.
                    </p>
                </footnote>.
                During the Debian package pre-configuration/configuration phase,
                <package>zope</package> package will prompt the
                <tt>shared/zope/restart</tt> shared Debconf question
                <footnote>
                    <p>
                        See <url id="file:///usr/share/doc/zope-dev/examples/templates" name="Zope tempalte file">,
                        and <manref name="debconf-devel" section="7">.
                    </p>
                </footnote>:
                while configuring, <package>zope-<var>foo</var></package>
                should use the answer to <tt>shared/zope/restart</tt> to
                decide how to configure the package. Possible reply are
                <footnote>
                    <p>
                        See <url id="file:///usr/share/doc/zope-dev/examples/postinst" name="Zope postinst file">,
                    </p>
                </footnote>:
                <taglist>
                    <tag>configuring</tag>
                    <item>
                        <p>
                            <em>Zope</em> should be restarted in the
                            configuration phase of the package installation.
                        </p>
                    </item>
                    <tag>end</tag>
                    <item>
                        <p>
                            <em>Zope</em> should not be restarted in the
                            configuration phase. The <prgn>postinst</prgn>
                            maintainer script should instead touch the
                            <file>/var/run/zope/restart</file> file: this will
                            trigger a test in
                            <file>/etc/apt/apt.conf.d/90zope</file> that will
                            restart <em>Zope</em> at the end of the whole
                            installation or upgrade process.
                        </p>
                    </item>
                    <tag>manually</tag>
                    <item>
                        <p>
                            <em>Zope</em> should not be restarted in any case:
                            the system administrator will handle it.
                        </p>
                    </item>
                </taglist>
            </p>
        </sect>
    </chapt>
    <chapt id="multiple_instance_guideline">
        <heading>Multiple Instances Guidelines</heading>
        <p>
            <em>Zope</em> package must comply to the following rules once installed:
            <taglist>
                <tag><tt>ZOPE_HOME</tt> and <tt>SOFTWARE_HOME</tt> path</tag>
                <item>
                    <p>
                        Python is an interpreted language and either
                        source or byte-compiled file are architecture
                        independent, so they should be placed under
                        <file>/usr/share</file> as for <em>FHS</em>. Since
                        that's not possible<footnote>
                        see Bug
                        <url id="http://bugs.debian.org/134762" name="#134762"> and
                        Python's forum <url id="http://python.org/sf/588756" name="588756">
                        </footnote><tt>ZOPE_HOME</tt> and
                        <tt>SOFTWARE_HOME</tt> must default to
                        <file>/usr/lib/zope/lib/python</file><footnote>
                        <tt>ZOPE_HOME</tt> and <tt>SOFTWARE_HOME</tt> are
                        going to migrate to Python's site-packages path.
                        </footnote>.
                    </p>
                </item>
                <tag><tt>INSTANCE_HOME</tt> path</tag>
                <item>
                    <p>
                        <em>Zope</em> support the concurrent running of
                        independent instances. Each instance uses a set of
                        files that may be atered multiple times during its
                        life time, so <tt>INSTANCE_HOME</tt> path should be
                        relative to <file>/var/lib/zope</file>. Suggested
                        value is
                        <file>/var/lib/zope/instance/<var>instance-name</var></file>.
                    </p>
                </item>
                <tag><tt>CLIENT_HOME</tt> path</tag>
                <item>
                    <p>
                        <tt>CLIENT_HOME</tt> must be directory relative to
                        <tt>INSTANCE_HOME</tt>. Suggested path is
                        <file>INSTANCE_HOME/var</file>.
                    </p>
                </item>
                <tag>Log files</tag>
                <item>
                    <p>
                        Any log file should be placed under
                        <file>/var/log/zope/<var>instance-name</var></file>
                        directory.
                    </p>
                </item>
                <tag>Pid files</tag>
                <item>
                    <p>
                        Any pid file should be placed under
                        <file>/var/run/zope/<var>instance-name</var></file>
                        directory.
                    </p>
                </item>
            </taglist>
        </p>
    </chapt>
</book></debiandoc>
