ZopeChanges

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
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 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 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]