Trac Object Model Proposal

Introduction

What is Trac?

Trac is a a minimalistic approach to web-based software project management. To that end, it features an enhanced wiki and issue tracking system.

The tight and coherent integration of its features is achieved by several means, but most notably by the consistent use of a unified language to talk about objects in the system (the TracLinks). This unique approach enables a powerful structuring of the information in the system, yet this can be achieved in a very flexible and informal way.

In this light, Trac is a semi-structured Wiki, where one can create and modify objects and talk about them

Trac Object Model

In the following, I'll try to show that Trac is a manager for typed pieces of informations: the Trac objects.

There are many advantages to gain by refactoring the internals of Trac to acknowledge this reality:

• more consitency, less redundancy, code simplication
• spreading the features available for one object to the other objects

This updated revision is made in light of the experience gathered while working on the #1242 patch.

Trac Objects

What can be consider as being a Trac object (TracObj) are:

• a wiki page (WikiPage)
• a ticket (Ticket)
• a changeset (Changeset)
• a milestone (Milestone)
• a report (Report)
• a source (Source)

Current State

Today, the various Trac objects are quite distinct objects. There is no code sharing between what defines objects and also not so much in the related Modules that manipulates objects.

Indeed, those objects have distinct features. But some degree of unification would actually make sense, both in term of increased functionality and in term of decreased code complexity.

Toward an Unification

What would be a generic Trac object?

• It would have a unique identity in the system — id
• It would have some wiki syntax to describe it
  • shortcut_regexp()
  • canonical_regexp()
• It would be displayed in several ways:
  • a canonical form — canonical_name()
  • a shortcut form — name()
• There could be one or several Wiki text attached to the object. Each would be a facet of this object. Some facets are:
  • content, appropriate for a WikiPage and a Changeset
  • description, appropriate for a Ticket, a Report and a Milestone
  • comment:n for the n^th comment
  • attachment:file for the attachment name file
• There would be some fields attached to it.
  • Some would be always there for the particular type of object considered
  • Some would be custom properties
• One would want to be able to attach files to any object
• One would want to be able to comment on any object, just like for a Ticket
• One would want to see the history of the modification of the object
  • the edit history of the main facet (see also TighterSubversionIntegration)
  • the change history of the value of the fields

Let's compare these generic feature with those of current Trac objects, and see what additional functionality and usages it would provide.

WikiPage

• The unique identity is the Wiki page name. — s/page_name/id
• The wiki syntax is the one described in WikiPageNames. — currently present in source:trunk/trac/WikiFormatter.py r"(?P<wikihref>!?(^|(?<=[^A-Za-z]))[A-Z][a-z]+(?:[A-Z][a-z]*[a-z/])+(?:#[A-Za-z0-9]+)?(?=\Z|\s|[.,;:!?\)}\]]))" and in source:trunk/trac/Search.py r = "((^|(?<=[^A-Za-z]))[!]?[A-Z][a-z/]+(?:[A-Z][a-z/]+)+)"
• The main facet would be content, i.e. the content of the Wiki page itself.
• The relevant fields:
  • author and creation time
  • a readonly boolean field
• Wiki attachments are there
• The change history would be contributed comments only, but that would make sense.
• Wiki history and revision diffs are there

Changeset

• The unique identity is the revision number — s/rev/id
• The wiki syntax is r"(?P<changesethref>!?(\[\d+\]|\br\d+\b))"
• The main facet is 'content', which is the original commit log entered in Subversion. See #781.
• Changeset properties:
  • author and creation time are those of the commit information.
  • Custom properties could be used for many things, as a way to annotate the revision. Some ideas are:
    • a boolean compilable flag (true by default, could be set to false to indicate that this revision can't be built)
    • a field indicating the % of successful test cases
    • a QA status
• Attachments for a changeset also make sense:
  • in case of a build failure, the corresponding errors from the compiler could be attached.
  • patches that applies to that revision
• A change history for a Changeset, wouldn't that be cool? Actually, the contributed comments could be used for code reviews The history and diffs for the commit log are useful once the changelog becomes modifiable

Ticket

• The unique identity for a ticket is its number — id
• The wiki shortcut syntax is r"(?P<tickethref>!?#\d+)"
• The main facet is description
• The ticket fields:
  • author and creation time
  • milestone and component
  • The short summary
  • The keywords
  • An optional due time
  • Assigned to…
  • Cc field
  • Custom properties as usual
• Attachments for tickets are there
• The change history is there
• The wiki history and diff would be usefull if the description is to be modified

Source

• The identifier for a file or directory is its path
• There's no facet attached to a source
• Fields
  • author, creation date
  • The size
  • The mime-type
  • dynamical svn properties
• attachments for files… Why not? One could already do it with Subversion anyway (svn pset prop -F attachment source)

Implementing Trac Objects

For processing Trac objects and for the logic associated to them, there would be a corresponding Module subclass (see TracPluggableModules). That is, some modules would use some kind of Trac objects:

• The WikiModule is using the WikiPage object.
• The TicketModule and the NewticketModule are using the Ticket object
• The Browser and Log modules will be using the Source object
• etc.

For the object-relational mapping, I would suggest having a table for each class, with common column names where appropriate (at the very least, the id column).

—ChristianBoos