History for ZopeChanges

??changed:
-
Amos (10/26) -- This is a work in process. Please add your comments in line.  I will try to respond to comments by refining this document.

How to Document Your Changes to Zope

  When you make changes to Zope you need to make sure that the
  official documentation gets updated to reflect your changes. Even
  simple changes can affect Zope documentation in ways that might now
  occur to you. To help keep Zope documentation up to date here is a
  check list. Whenever you make a change to the Zope core distribution
  please go through this check list to see what needs updating.

    1. Does your change affect any Zope management screens. For
       example, did you add any new views on any existing objects, did
       you remove any views from any objects, did you change any views
       of any objects? If so, you need to update the online help for
       the changed views. Here's how to do it:

         1. Figure out which views are changed/added/deleted. You can
            figure this out by checking the 'manage_options' structure
            on the affected class(es).

         2. Change the help topics for the changed views. Delete the
            help topics for deleted views and add new help topics for
            new views.

         3. For more background on creating help for management
            screens see "How to Document your Zope Product":ProductDoc

    2. Does you change affect any public APIs? For example, did you
       make changes to the behavior, signatures, or permissions of
       documented methods of documented classes? Check the API
       reference in the online help to be sure. If you did change
       something that affects the API reference, update the API
       reference. See "How to Document your Zope Product":ProductDoc for more
       information about API reference documentation.
 
    3. Does your change affect DTML tags? For example did you change
       the behavior of a tag, add a new tag, or add a new utility
       function? If so you need to update the affected DTML reference
       files in 'lib/python/Products/OFSP/help'. The DTML Reference
       files have names like 'dtml-tagname.stx'.  See "How to Document
       your Zope Product":ProductDoc for more information.

    4. Does your change substantially affect Zope in other ways? For
       example, did you add a new object to Zope, did you add a new
       network protocol, did you change how the control panel or
       ZClasses work? If your change is user-visible in some way it
       should be documented. Here's how:

         1. You should already have changed any management screen,
            API, and DTML documentation.

         2. You should summarize your changes in plain English using
            examples and send the summary to [email protected]. We
            will work your changes into the Zope book.

    5. There is not currently a procedure to document changes that are not user-visible. For example, if you add a new hook to 'ObjectManager' there is currently no place to document this, besides in the code. As we develop a comprehensive plan for developer docs this will change.

  If you have a question about your changes, please write to
  [email protected]