Changes between Version 2 and Version 3 of TracObjectModelProposal

Timestamp:

Nov 21, 2004, 11:38:24 AM (19 years ago)

Author:

cboos@…

Comment:

Finished the first draft of the proposal

TracObjectModelProposal

@@ -1 +1 @@
 = Trac Object Model Proposal = 
+
 
 == Introduction ==
@@ -11 +12 @@
  * A search facility that covers all the text content of Trac
 
-The integration is achieved by several means:
+The tight and coherent integration of these features is achieved by several means:
  * tracking of a single software repository
  * using a simple relational database to store all the informations
    about tickets, milestones, changesets and wiki pages.
  * using a unified ''language'' to talk about objects in the system,
-   by the way a wiki syntax (TacLinks) which can be used nearly everywhere:
+   by the way of a wiki syntax (TacLinks) which can be used nearly everywhere:
    * in Subversion commit log messages
    * in Ticket descriptions and comments
@@ -29 +30 @@
 ''objects'' and talk about them
 
+
+'''In the following, I'll try to show how those Trac ''objects'' are variations on a same theme, both from the data point of  view and from the behavioral point of view.'''
+
+
+
 == Trac Objects ==
 
 What can be consider as being a Trac object (''TracObject'') are:
- * a wiki page (''WikiPage'')
+ * a wiki page (''!WikiPage'')
  * a changeset (''Changeset'')
  * a ticket (''Ticket'')
@@ -38 +44 @@
  * an attachment (''Attachment'')
 
+
 === Current State ===
 
@@ -45 +52 @@
 objects.
 
-Indeed, to those objects correspond some distinct features.
-
-But it strikes me that some degree of unification 
-actually makes a lot of sense, both in term of increased 
-functionality and decreased code complexity.
+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 ===
@@ -56 +63 @@
   * It would have a unique identity in the system
   * It would have some wiki syntax to describe it
-    (a ''canonical'' form and also a shortcut form if possible)
+    (a ''canonical'' form and also a ''shortcut'' form if possible)
   * There would be obviously a Wiki description of it
   * There would be some properties attached to it:
@@ -65 +72 @@
     * Some would be ''custom'' properties
   * One would want to be able to attach files to that object
-  * The content of the object could be modified, so there
+  * After the main wiki content, there could be a change history, 
+    a sequence of summary of commented property changes (or just comments)
+  * The Wiki content of the object could be modified, so there
     would be an history of changes, the possibility to make
-    diffs between revisions of the object (see also TighterSubversionIntegration)
-  * In addition to the main wiki content, linear (or even hierachical!) contributions
-    in the form of short comments could be added
-
-Let's cross these generic feature with the current Trac objects,
-and see to what existing functionality it can be related, 
-and what additional functionality and uses it would provide.
+    diffs between revisions of wiki (see also TighterSubversionIntegration)
+
+Let's compare these generic feature with those of current Trac objects,
+and see what additional functionality and usages it would provide.
 
 ==== WikiPage ====
@@ -80 +86 @@
  * The wiki syntax is the one described in WikiPageNames.
  * The Wiki description would be actually the content of the Wiki page itself.
- * The universal properties (author and creation time) are there, 
-   but there would be no specific properties for Wiki. 
-   ''custom'' properties could make sense, but as usual with ''custom''
-   properties, their presence and pertinence is site-dependant.
- * Wiki attachments
- * Wiki history and revision diffs
- * Wiki comments would make sense, as highlighted 
-   in the Enhancement Request #xxx (TODO)
+ * Only a few properties are relevant:
+   * The universal properties (author and creation time) are there, 
+   * There's no need for specific properties for a !WikiPage
+     (except maybe a ''readonly'' attribute?)
+   * ''custom'' properties could make sense, but as usual with ''custom''
+     properties, their presence and pertinence would be site-dependant.
+ * Wiki attachments are there
+ * The change history would be contributed comments only, but that would make sense.
+   That feature is mentionned in the MacroBazaar page.
+ * Wiki history and revision diffs are there
 
 ==== Changeset ====
 
-
-''(Sorry, work in progress, hang on...)''
+ * The unique identity is the revision number
+ * The wiki syntax is {{{changeset:XYZ}}} or {{{[XYZ]}}}
+ * The Wiki description is the original commit log entered in Subversion.
+   This is normally not meant to change, though it can sometimes be
+   handy to fix a typo (therefore the occasional use of the 
+   {{{svnadmin setlog}}} command). There are 3 possibilities:
+   * Keep it as it is (read-only)
+   * Enable ''trac-only'' modifications
+   * Provide the functionality of {{{svnadmin setlog}}}
+ * Changeset properties:
+   * The universal properties (author and creation time) are those 
+     of the commit information.
+   * The properties specific to a Changeset could be the list of node changes
+     corresponding to that revision.
+   * 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 be that extreme?
+   Actually, the contributed comments could be used for code reviews,
+   another long standing request (#YYY TODO)
+ * Wiki history and diffs would be usefull if the changelog is to be modified
+ 
+==== Ticket ====
+
+Introducing an object hierarchy was indeed the initial motivator for this proposal. 
+While thinking about request for ''MasterTicket''s (#886), it struck me
+that ''Milestone''s could be seen as a kind of tickets.
+
+(I explained elsewhere (#919) the reasons why I think a categorization of tickets
+can be important. However, the approach taken in that proposed patch, is, 
+well, just a patch.)
+
+A hierarchy of ticket classes would better serve the purpose of a categorization.
+It can achieve a better repartition of the specific properties. 
+The relationships between these categories could also be done in a modular way.
+
+First I'll describe the generic ticket as I did above for the other Trac objects, 
+then I will describe a hierarchy of tickets.
+
+ * The unique identity for a ticket is its number
+ * The wiki syntax is {{{ticket:XYZ}}} or #XYZ
+ * The Wiki description for that object is the Ticket description
+ * The ticket properties:
+   * The universal properties (author and creation time) also apply here
+   * The specific properties would be:
+     * 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
+
+A generic event can be used to dispatch some information immediately, 
+or to indicate some future event (this needs to be coupled to 
+#ShowFutureEventsInTimeline -- oh, by the way, what about #TicketAliases ?)
+
+Then, I would propose the following subclasses:
+ * a !TaskTicket: ''something to be done about something''
+   * Additional specific properties:
+     * Severity: ''what is the impact of this task?''
+     * Priority: ''what's the most urgent task among the urgent tasks?''
+     * Milestone: ''to what Milestone'' object does it relate?
+     * The related component(s) ''(well, a Component could also be a Trac object...)''
+     * Status (opened/closed)
+     * Resolution: ''in which way the task has been completed''
+ * !ProblemReportTicket would be a simple subclass of !TaskTicket
+ * !EnhancementRequestTicket would be a simple subclass of !TaskTicket
+ * !MilestoneTicket: ''a collection of Tasks that will happen sometime (due time either set or opened)''
+
+Other possible Ticket types:
+ * Information: ''just to pass some news around (its due time is present)''
+ * Deployment: ''a specific build has been made available''
+
+==== Attachment ====
+
+ * The unique identifier for an attachment would be its filename, 
+   plus the unique identifier of the object it is attached to.
+ * There's currently no wiki syntax associated to an attachment,
+   though in #944, I propose the {{{attachment:filename}}}. 
+   This currently works only from the Wiki of the parent object,
+   the one to which the file is attached. What would be needed would be:
+   {{{attachment:<TracLink>:filename}}}, where !TracLink would specify
+   the parent object.
+ * The Wiki content would be the optional file description
+ * Properties:
+   * The universal properties also apply for attachment
+   * The specific properties would be:
+     * The size
+     * The mime-type
+ * Ok, attachments for attachments. Now ''that'' does not make sense...
+ * Change history would probably be overkill 
+ * Wiki history and diff would probably be overkill here too
+
+But have a look to the TighterSubversionIntegration proposal
+to see that those last features would in some cases prove usefull...
+
+==== Component ====
+
+This would be a subtype of a !WikiPage. 
+Therefore it would share most of what has been said for !WikiPage.
+
+In addition, there would be specific fields, 
+like a list of repository paths describing the component 
+in term of software artifacts.
+
+This would allow the following features:
+ * automatically relate a Changeset to the affected components.
+ * filter the Changesets in the Timeline to those belonging
+   to a component
+
+This is just an example of a new type of Trac object.
+It may or may not sounds like a good idea, but by the way of the
+object model, its implementation would essentially focus
+about how it would interact with the Changeset and Timeline modules.
+
+See also TracReleaselist for the Release object...
+
+
+=== Summary ===
+
+The above correspond to the following hierarchy:
+ * !TracObject
+   * !WikiPage
+     * Component
+   * Changeset
+   * Ticket
+     * Task
+       * !ProblemReport
+       * !EnhancementRequest
+     * Milestone
+     * Information ''*''
+     * Deployment ''*''
+   * Attachment/File
+
+
+== Implementing Trac Objects ==
+
+For processing Trac objects and for the logic associated to them, 
+there would be a corresponding {{{Module}}} subclass
+(see TracPluggableModules).
+
+Therefore, the Trac object hierarchy outlined above will closely corresponds to a 
+hierarchy of Python Module classes:
+
+ * Module (much of the current Ticket code would be moved here)
+   * Wiki
+     * Component
+   * Changeset
+   * Ticket
+     * Task
+       * !ProblemReport
+       * !EnhancementRequest
+     * Milestone
+   * Attachment/File  (see TighterSubversionIntegration)
+
+But not only that, the Trac object hierarchy will also correspond to a specific
+object model for the schema in the database.
+
+There is essentially two approaches for the object-relational mapping:
+ * For a class, have multiple tables, one for each level in the 
+   hierarchy, and join them on the shared identifier.
+   The root level contains also the type of the object.
+ * Have a table for each class, with common column names
+
+Each solution has its pros and cons. I will adopt the first approach here,
+to get things started.
+
+Common to all the Trac Objects, there would be a main table
+and some auxilliary tables:
+
+{{{ 
+#!sql
+
+-- TracObject
+-------------
+
+CREATE TABLE trac_object (
+       id               text PRIMARY KEY,
+       type             text,
+       time             integer,        -- the time it was created
+       author           text,
+       description      text,
+);
+
+-- for the change history of any TracObject
+-------------------------------------------
+
+CREATE TABLE object_change (
+       id               text,
+       time             integer,
+       author           text,
+       field            text,
+       oldvalue         text,
+       newvalue         text,
+       UNIQUE(id, time, field)
+);
+
+-- for the custom fields associated to any TracObject
+-----------------------------------------------------
+
+CREATE TABLE object_custom (
+       id               integer,
+       name             text,
+       value            text,
+       UNIQUE(id,name)
+);
+
+CREATE TABLE object_custom_multi (
+       id               integer,
+       name             text,
+       value            text
+);
+}}}
+
+Each Trac object would eventually have an extension table,
+to represent its specific fields:
+
+{{{
+#!sql
+
+-- Ticket (or Milestone)
+------------------------
+
+CREATE TABLE ticket (
+       id               text,
+       summary          text,
+       keywords         text,
+       duetime          integer,
+       owner            text            -- who is this ticket assigned to
+);
+
+-- Task (or PR/ER)
+------------------
+
+CREATE TABLE task (
+       id               text,
+       severity         text,
+       priority         text,
+       milestone        text
+);
+
+-- Report
+---------
+
+CREATE TABLE report ( 
+       id               text,
+       title            text,
+       sql              text
+);
+
+-- WikiPage
+-----------
+
+CREATE TABLE wiki ( 
+       id               text,
+       readonly         char(1)
+);
+
+}}}
+
+Note: the Changeset doesn't need anything in addition to the TracObject fields.
+
+
+Finally, there would be auxilliary tables for some objects:
+
+{{{
+#!sql
+
+-- For Changeset
+----------------
+
+CREATE TABLE changeset_node_change (
+       id               text,
+       path             text,
+       change           char(1)
+);
+
+-- For Component
+----------------
+
+CREATE TABLE component_path ( 
+       id               text,
+       path             text
+);
+}}}
+
+
+== Summary ==
+
+This proposal aims both at a simplification of the current Trac implementation,
+which contains a different data representation for each Trac object, and at 
+enhanced functionalities, because the rich functionality that is currently 
+available for Ticket (attachments, change history, custom fields)
+would be also available for !WikiPage, Report, Changeset, Attachment/File and of course,
+subtypes of Tickets, like Task and Milestone.
+
+This does not mean that all these objects are interchangeable, or that any
+specific functionality would be lost in the process. Quite to the contrary,
+each module could focus on what makes it unique, and in which ways it 
+can interact with the other modules, leaving to the generic {{{Module}}}
+all the shared functionality.
+
+
 ''--ChristianBoos''