History for ZenFromZopeCoders

++added:
A guide to being a Zope Coder

  *"Steve Alexander":mailto:[email protected] started on 29 September 2001*

  First, a note that this is just one of many ways of doing things.
  It may not even be the best, but here it is anyway.

  I haven't credited everyone who said everything. This is sort of deliberate, and sort of because I am lazy. I'm hoping that this will transform itself into a number of documents with correct answers and procedures in them, and thus it won't matter exactly who said what.

  The information here is compiled from posts to the Zope-Coders list, and
represents a How-To guide to being a Zope Coder -- a person with check-in
rights to the Zope CVS.


  Definitions

    Here are some definitions of terms used when talking about working with CVS and Zope.

    Sandbox

      A directory on your own computer where you check out a branch from CVS and do work on it. This work can be experimental, as it is in your own sandbox.

    Sandbox checkouts

      These are checkouts on a branch (for example chrisw-zeowait-branch) for testing a prototype of a new feature.
  
      You might want to test out a new feature by making a sandbox on a branch, making a small (1/2 page) fishbowl project, and seeing if it generates dissent, and lobbying the zope core team.
  
    Current branch
  
      The current release branch. At the time of writing, it is Zope-2_4-branch.
  
    Trunk
  
      The trunk should never be in a state where we would be uncomfortable making an alpha or beta from it on 2 days notice.
      The trunk represents the latest stable, pretty well tested, ready to run Zope.

    The head
  
      Same as the Trunk


  Places to look for more information

    "This page":http://dev.zope.org/CVS/ZopeSVNFAQ (http://dev.zope.org/CVS/ZopeSVNFAQ) walks you through checking out Zope, cvs branches, how to change work in branches, and commit that work back into releases.

    http://dev.zope.org/CVS/CommitterGuidelines

    You can see who owns the large-scale projects related to Zope 
  "here":http://dev.zope.org/CVS/RepositoryProjects (http://dev.zope.org/CVS/RepositoryProjects)

    http://lists.zope.org/pipermail/zope-checkins/2001-September/date.html
  
  
Recommended practices

    Document functional-style code with a short explanatory comment.
  This includes map, reduce, filter, list comprehensions.

    Code checked in *must* work with the currently officially supported Python version, and it *should* work with later versions when possible and practical.
    The current officially supported Python at the time of writing is 2.1.

    Do not compare by type::

      if type(foo) == type(''):

    Instead, use 'instanceof'::

      import types
      if instanceof(foo, types.StringType):

    Don't use this common idiom::

      if type(foo) in (StringType, UnicodeType):

    as it will break after the type/class unification starting in Python 2.2.

  Brian Lloyd on supporting unicode::

    The official policy statement is: we don't want to be writing
    new code that (intentionally) would prevent unicode from being 
    used in a given situation.

    Getting Zope unicode-friendly will take time, and will need to 
    be tackled in a number of projects. Some will tackle actually 
    making use of unicode (for I18N), and others will be concerned 
    with fixing old code that is not prepared to see unicode.

    Most of the hard issues will be dealt with in the proposals and 
    other artifacts of those projects. When we run into (presumably 
    smaller) unicode-related issues in other work, the right answer 
    is to either make the code unicode-friendly (for minor things) 
    or to escalate the issue to a proposal (when we run into an 
    unexpected can of worms).


  Email addresses for project owners

    [email protected] for CMF

    [email protected] for Zope core.

    Chris McDonough has worked on ZCatalog, and can approve checkins.

    Andreas Jung is the current ZCatalog owner.

    Brian Lloyd is the owner of STX.

    The boundaries of ownership of packages in Zope are pretty flexible.

CHANGES.txt

    The path to the file is doc/CHANGES.txt. It lists the changes that have been made to Zope since the last released version.

    If you're fixing a bug, you only need to add to CHANGES.txt in the branch.  If you're adding a feature, you only need to add to CHANGES.txt in the trunk.  Brian Lloyd later stitches them together.

Bugs fixed and Features added  

    There should be a section "Features added" and "Bugs fixed" for every
release or version inside CHANGES.txt. We usually append a comment to the
end of the corresponding section.

    You append your change to the end of the "Features added" or "Bugs fixed" section. The section to use is that for the current release, which appears at the top of the CHANGES.txt file.

    The changes for each release are in reverse-chronological order by release.  if you're changing the release branch's CHANGES.txt and there's no entry for the release you're working on (let say, for instance, it hasn't been released yet! ;-), just make a section named "Unreleased" and put the comments under it.



    You should usually put a note in CHANGES.txt for each change you make. You should identify the note with your initials or some other identifier, so that it is easy to see who was responsible for what if there are questions later.

    Note that it's usually a good idea to reference the Collector issue number in the CHANGES.txt. 

  *Q:* Should all changes get a note in CHANGES.txt?

  *A:*  Use your own judgement, but it is generally good citizenship to 
    make a note of things you've done (if for no other reason, other 
    people can tell that you've already taken care of a problem 
    without wading through CVS logs). Excruciating detail is not 
    necessary. A note of "The docstrings in Magic.py were way too 
    terse, so I rewrote many of them to be more clear" is fine.


An example: the no-brainer bugfix

    This is a special case where there is an obvious typo that obviously
  doesn't affect anything else.
  
    Such a bugfix can be checked directly into bother the current branch, and the trunk. A note should be added to the CHANGES.txt on the current branch.
   

On bugs, bugfixes and features

  Tim Peters says:
  
    A bug is actually (at least) two bugs:  the obvious bug, but also a bug in
  the test suite that failed to catch it (since a test suite's purpose is to
  catch bugs, a bug it misses is by defn. a failure of the test suite to do
  its job).
  

  The difference between bugfixes and features

    Bugfixes

      No documentation obligations, except CHANGES.txt
      (unless it is a documentation bugfix)

      Should update unit tests like this

          Either correct a "faulty" test that let the bug through,
        or add a new test that would have caught the bug, and 
        passes the fix. Don't forget the rationale.

          Don't worry about test suites getting too bloaty.
        It is easier to remove / rationalize them if they are there
        in the first place!

      Reference the collector id in the CHANGES.txt and checkin log

      Should be checked into both Trunk and Stable releases.

    Features

      Usually have documentation, UI, and other dependencies.

      Normally need a fishbowl project, although, can be a small 
      1/2 page fishbowl document.

      Never check a feature into a stable release!

      Be careful with adding small features; they often touch a lot of things.
      Best to ask about it on zope-dev or zope-coders. Remember, features can
      touch protocols, UI, documentation, ...

Tests

  *Q:* Is the process for running the Zope tests the same or should I use
    testrunner.py?

[293 more lines...]