Zope 3 wiki → Developer Info → Proposals →
last edited 2 years ago by srichter
created: 2005-08-04

Developer Mode

Developer Mode

Status

IsImplementedProposal

Author

StephanRichter

Problem

Currently developer-related features, such as the introspector and apidoc, are always turned on, unless someone deletes the correct files from the package-includes/ directory.

Goals

I would like to implement a developer's mode, which can be turned on/off inside the Zope configuration file (zope.conf). Developer-related features are only loaded and available when the developer's mode is turned on.

Motivation

  • Currently there are many menu items and help pages available, even if the user is not a developer. This is simply because the developer forgets to turn off the development tools. And once turned off, it's a pain to turn them back on. You either have to edit or add/delete several ZCML files.
  • By nature of API documentation a lot of information is revealed. This also poses a security risk, since information might be provided that is otherwise protected.
  • Loading all of the API documentation and the many text files has a fairly large impact on the startup time. By actually not loading the developer-documentation related configuration files and directives, we can save easily 2 seconds in the startup time.

Proposed Solution

The Switch

During the discussion of the proposal, we identified three possible methods to implement the devmode switch:

(1) A new option is the zope.conf configuration file will be provided to turn the developer's mode on and off: 

           #
           # devmode
           #
           #   Switches the Developer Mode on and off.
           #
           # Default:
           #   devmode off
           #
           devmode on

By default the switch will be turned off. When turned on, a ZCML feature (developer-mode) will be added to the configuration context before evaluating any file. This will allow us to load the configuration selectively.

(2) Philipp thought that zope.conf is for configuring the webserver and ZODB databases. Its job is not to configure policy of the application that's running on Zope. That's ZCML's job.

He suggested to put the following command into 'site.zcml': 

          <meta:provides feature="developer-mode" />

The way to turn the the developer mode on and off is by simply uncommenting and commenting this line.

I strongly disagreed with this suggestion, since zope.conf is the right place to implement the switch. Developers should never touch site.zcml.

(3) After some discussion on IRC, Steve and Philipp suggested to have a new developer-site.zcml file with the following contents: 

          <configure 
              xmlns:meta="http://namespaces.zope.org/meta">

            <meta:provides feature="developer-mode" />
            <include file="site.zcml" />

          </configure>

Then in zope.conf, you'd use the site-definition switch to either point at site.zcml or developer-site.zcml. This way no new Python code has to be written and the developer mode can easily be turned on and off in the zope.conf file.

I like the third approach a lot, since all my design goals are met and the implementation is simpler. Obviously this also has the support from Steve and Pilipp.

Also, some mechanism will place an additional layer (IDevModeLayer) in the request, so that we can register special views in that layer only for develoepr documentation purposes. Possible options for this mechanism include a traversal event hook or a hook into applySkin().

The User Interface

It should be very clear in the UI that you are in developer mode. One way to achieve this goal is to provide a custom stylesheet. Additionally, I propose that we put the developer's options in a totally different menu that is not part of the flow of the site. Here is what I have done for SchoolTool?:

Identified Developer Tools/Documentation

  • API doctool

    This documentation will only be available in developer mode, since it serves no other purpose.

  • Introspector (see Introspector NG)

    As for the API doctool, the introspector will only be available when the developer mode is activated. This is a logical choice, since the implementation of the introspector heavily depends on the API doctool.

  • Error Reporting Utility

    The error reporting utility will be installed in all modes, since it can be useful in production as well. However, we will remove the Errors menu item from zmi_actions in general and only make a link to the error reporting utility available in the "Developer Tools", which is of course only available in developer's mode.

Risks

I have already implemented this feature in SchoolTool? and it works great there. So we would only need to port the code.



( 98 subscribers )