History for WhatGoesWhereAndHow

??changed:
-
What Goes Where and How

  The repository consists of applications and also directories of
  elements which are typically shared among the applications.  Anyone
  making additions to the repository must understand the sharing
  arrangements to know how to properly situate the additions.  
  There are facilities (controlled by checking in recipe files) for
  managing the interconnections and for directing the destinations
  for checkin notices.  This is all described below.

  See CVSAddons for a description of the ingredients and hookup of our
  special CVS provisions that implement the sharing and notifications, etc.

  Organization

    The short story re organization is that only application-specific
    stuff should go directly in the application sections of the
    repository.  Lots of stuff should wind up in Packages (and get
    linked into the application(s) where its used via the
    CVSROOT/repolinks), except for Zope products which go in Products.

      Products -- Zope python-based extension packages.  The Zope
                  repository section links to the standard products
                  from Zope/lib/python/Products.

      Packages -- Non-Product python packages used in the various
                  repository applications.

                  You would generally expect to add to Packages when
                  adding a substantial element to any application, and
                  link the package in to the application skeleton.

      Docs -- General Zope-related documentation, and application
              specific documentation directories.

      Various Applications -- Zope, !StandaloneZODB, ZEO, and
              others as they emerge.  These directly contain the
              application-specific elements, plus links to the
              Packages, Products (in the case of Zope), and Docs for
              sharable elements.

       Cruft -- shared stuff that doesn't have a proper place in the
                other official places.

    (There is also a few legacy items: Zope2 is an old name for the
    Zope checkout, no longer being actively maintained.  Releases was
    a temporary provision - it has been redirected, to support old
    checkouts, but will soon be removed.)

  Sharing of Repository Elements

    Repository element sharing is arranged using symlinks in the
    repository.  (We can't use standard CVS 'modules' due to severe
    deficiences, described in
    http://mail.zope.org/pipermail/zope-announce/2001-August/000517.html .)
    Those symlinks are governed by a textual list in the
    CVSROOT bookkeeping directory, CVSROOT/repolinks.  People with
    checkin privileges can change the sharing structure by changing
    this file.  You should really know where things belong before
    messing with the structure - if you are unsure, contact the people
    on mailto:[email protected] (so everyone can get filled in on
    the answers), or contact the mailto:[email protected] directly if
    you're shy.

    The CVSROOT/repolinks file has comments at the top describing the
    format.

    The CVSROOT/adjustlinks.py script is automatically invoked to
    apply the link map prescribed by repolinks.  The docstring for
    !LinkMap.assert_links() method details the actions - here's a
    current (08/07/2001) snapshot::

        """Impose the links specified by the recipe, removing preexisting
        links that are not specified in the map.  Specifically:

          - Add prescribed links that are absent, when there's no non-link
            file in the way.

          - Adjust already-existing links that don't point to the prescribed
            place - so we can use the recipe file to redirect existing links.

          - Remove links that are not prescribed.

          - Do nothing for links that already exist as prescribed.

          - Warn about prescribed links that point nowhere.

          - Warn about prescribed links that cannot be created because the
            indicated containing dir does not exist.

          - Reiterate attempts until all are done, or no more progress is
            being made - so it's not a problem for links to be dependent on
            others in order to be situated.

          - Delete prescribed links that point outside the repository.

          - Produce output about all the actions."""

    The warnings and info messages resulting from application of
    the script are sent to the "digicool-cvs",
    http://lists.zope.org/mailman/listinfo/digicool-cvs mailling
    list.

  Checkin Notices

    Checkin notices about all checkins are dictated by another
    script we've added to CVS central bookkeeping,
    CVSROOT/traffic_table.py .  Using entries in that table you
    can cause checkin notices for a particular section of the
    repository to be directed to any email addresses - typically
    we send them to mailling lists.  Notices for any checkins not
    corresponding to a particular entry are sent to  the
    "zope-cvs", 
    http://lists.zope.org/mailman/listinfo/zope-cvs list.

    Note that the checkin mechanisms account for the repository
    symlinks dictated by repolinks.  Ie, all relevant entries for
    an element will be triggered, even if that entry contains the 
    directory where the checkin was made only indirectly, due to
    symlinking.