= Trac Object Model Proposal ''This proposal is about unifying the capabilities of the various Trac objects, by making them inherit from a common `TracObject` class. The goal is to expand the feature set of Trac while simplifying its implementation.'' == Introduction === What is Trac? === Trac is a ''a minimalistic approach to web-based software project management''. 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 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 consistency, less redundancy, code simplication * spreading the features available for one object to the other objects This updated revision is made through the experience gathered while working on the TracCrossReferences feature: for implementing generalized back links, I had to have a common interface to all the Trac objects, this was a practical reason to introduce the `TracObject` (see source:sandbox/trac-xref/trac/object.py). == Trac Objects What can be considered a Trac object (`TracObject`) are: * wiki pages (''!WikiPage'') * tickets (''Ticket'') * changesets (''Changeset'') * milestones (''Milestone'') * reports (''Report'') * sources (''Source'') === Current State in `trunk` 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 manipulate 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. Last discussed examples were the ability to add comments on various objects, (this [http://thread.gmane.org/gmane.comp.version-control.subversion.trac.general/5609 thread], ticket #2035), the ability to query over other objects than just the tickets (#2465), and several other examples (query:keywords~=object). === Towards an Unification What would be a generic Trac object? * It would have a unique identity in the system This would be the `type` and `id` properties. * It would have some wiki syntax to describe it * It would be displayed in several ways: * a ''canonical'' form -- `fqname()` e.g. `wiki:WikiStart` * a ''shortcut'' form -- `shortname()` e.g. `WikiStart` * a ''display'' name -- `displayname()` e.g. `Ticket #123` * It should be addressable * `href()` method * `anchor()` method * There could be one or several Wiki text attached to the object. Each would be a '''facet''' of this object (''FIXME: I'm looking for a better name than ''facet'')'' [[BR]] 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 * 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 (like the ''Page History'' for a Wiki page) * the change history of the value of the fields (like the ''Change History'' for a Ticket) Let's compare these generic features with those of current Trac objects and see what additional functionality and usage it would provide. ==== Wiki Page The Wiki Page object would gain the ability to have custom fields. ==== Changeset The changeset message can be considered to be a ''facet'' for that object. Editing the message would be handled very similar to editing the wiki page content (see #781). It will be versioned, like the content for wiki pages are. If the underlying VersionControlSystem supports it, the change could be reflected in the repository itself. Not all versioning systems support that: e.g. SVN does, but Mercurial does not. A `resync` operation would simply add a new revision for the message, if something changed. 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. The contributed comments could be used for code reviews. It would also be nice to be able to query changesets (see #2465). ==== Ticket There's currently no way to have an history of the description facet. Otherwise, the Ticket has pretty much all of the generic functionality. There's also the question of having greater flexibility for ticket fields: * different sets of fields for different types of tickets (see #2464) * less difference between custom ticket fields and ''normal'' ticket fields (some kind of unification would be great here) * possibility to have multiple values for a field (see #221, #918 and #1730) There's also the question of bringing together Milestone and Ticket objects for implementing SubTickets. ==== Source Currently, there's no facet attached to a source. One could imagine having a summary or description facet. This could give a repository browsing experience close to what Sun did for [http://cvs.opensolaris.org/source/xref/on/usr/src/ OpenSolaris]. ''--ChristianBoos'' ==== Enterprise Objects > SOAP/REST support, permissions and security, in TRAC Objects could allow interface to > remote resources and distributed functionality. [[br]] > ''--Jim Scarver'' I'm not completely sure about what Jim meant in the above, but there's certainly a connection between this proposal and the security aspects, as can be seen in Alec's [TracDev/SecurityBranch permission policy] proposal. === Related Proposals - TracDev/Proposals/DataModel - common data structures for all the Trac resources. - TracDev/Proposals/Journaling - focusing on the data structures, APIs and interfaces dealing with changes happening in Trac objects. - TracCrossReferences - generalized back-references and relationships between Trac objects.