0.3 Directory Structure Proposal

Where do we put things?

We're midway through the process of making some sweeping changes: removing zodb completely, killing viewer parcels as we knew them, refining our idea of parcels, introducing documents and blocks, using agents for asynchronous tasks like loading rss data into the repository (zaobao), etc. As part of these changes, we've had some confusion about what should live where, both in the cvs filesystem and in the repository. This proposal attempts to get consensus about where we put things, so we can stop worrying about it and move on to more interesting issues.

This document is meant to address the problem as faced in Nov/Dec 2003, not meant as a living document that tracks the directory structure for all time. Presumably once we get critical mass (in the 0.3 release timeframe), this will no longer be an issue.

Status

We took the first pass at these changes. Remaining work:

• Rationalize AutoKind/AutoItem with parcel loading
• agent test code
• Cleaning up old directories (after cpia is done)

Would be nice to be done by the next milestone (0.3.04)

Proposal for CVS directory structure

• Chandler
  • Chandler.py
  • application
    • Application.py
    • Globals.py
  • parcels
    • OSAF (not changing to lowercase due to CVS limitations)
      • AppSchema => framework done
        • agents (from Chandler/application/agents) done
        • notification (from Chandler/application/agents/Notifications) done
        • DocumentSchema => blocks done
        • tests (new)
        • utils
      • PimSchema => contentmodel done
        • CalendarSchema => calendar done
          • tests (new)
        • ContactSchema => contacts done
        • EmailSchema => mail done
        • TaskSchema => tasks done
        • NoteSchema => notes not there
        • tests (new)
      • templates
        • top
      • examples
        • mrmenus
        • stockquote
        • timeclock
        • zaobao
  • repository
    • item
    • packs
    • persistence
    • schema
    • util
    • parcel (new) done
      • repository/schema/ParcelManager.py => ParcelManager.py done
      • repository/schema/LoadParcels.py => LoadParcels.py done
      • repository/schema/Parcel.py => Parcel.py done
    • tests

Proposal for Repository layout

• repository skipped
  • schema
    • core
• parcels done
  • <Mirrors cvs directory structure under 'parcels'>
• userdata done
  • views
  • agents
  • contentitems
  • indexes
• autoitems skipped
  • <Mirrors cvs directory structure under 'Chandler'>

Notes

• Change the name AppSchema --> framework. This directory will contain framework parcels, lumping framework schema with other items.
• Move agent code to framework (in parcels) out of application
• Move notification code outside of agents, into framework
• In the repository, userdata is meant as a location for data created for this user (the actual contacts, calendar events, etc.)
• unit tests can be found in "tests" directories, near the code its testing

Issues

• Captialization chaos resolution: all directories in cvs should be lowercase.
• Do we want to think of zaobao as a thirdparty parcel, or as part of the app? timeclock? stockquote? (all are in an 'examples' section, not really thirdparty, not part of the primary application)
• Should data created at runtime live separately from data loaded in parcels? (yes) If so, should the structure of 'userdata' mirror the structure of parcels? (no)
• Where do AgentManager and NotificationManager live? resolution: The code related to agents lives in an agents parcel, the code related to notifications lives in a notifications parcel. The application creates a singleton AgentManager and a singleton NotificationManager, placing them in a global variable. These global singletons live in Globals.py, and can be accessed by parcels that might need them.

Terminology Issues

Latest terminology news from the design team (via Brian):

• Official capplet names (for use in directory structures and project list):
  • "Contacts"
  • "Calendar"
  • "Mail"
  • "Tasks"
  • "Notes"
• Some things stay the same:
  • "osaf" --> "osaf"
  • "parcel" --> "parcel"
  • "capplet" --> "capplet"
  • "context" --> "context"
• And other things change:
  • "document" --> "view"
  • "info item" --> "content item"
  • "template" --> "view template"

Discussion, complaints, proposed changes

• Noting Stuart's objection: too hierarchical, annoyingly long class path names. To make the code readable, one can do: import my.long.package.name.module as module.

-- KatieCappsParlante - 13 Nov 2003