Changes between Initial Version and Version 1 of TracDev/Proposals/ProjectLabels

Timestamp:

Jan 3, 2012, 4:57:53 AM (12 years ago)

Author:

olemis+trac@…

Comment:

Initial proposal for project labels (classifiers) complementing wiki:TracDev/Proposals/MultipleProject

TracDev/Proposals/ProjectLabels

@@ +1 @@
+
+= Project classifiers (aka labels) = #Introduction
+
+  Consider merging this page with 
+  [wiki:TracDev/Proposals/MultipleProject Multi-Project Support for Trac]
+
+In order to provide an structured solution so as not to limit the possible ways of 
+grouping projects it is convenient to introduce the concept of 
+'''project labels'''. Main goals are the following :
+
+  - Offer a structured mechanism to identify a group of projects no matter 
+    what hierarchy is involved .
+  - Encapsulate these details at the API level while 
+    determining (multi)project context.
+
+Considering the [wiki:TracDev/Proposals/MultipleProject#ProjectTree reference example], 
+in spite of searching for tickets 
+in `Family A` and `Family B` but not in `Tools` and `3rdParty` when needed, 
+a label containing both projects has to be created (either ''explicitly'' or 
+''implicitly'', see [#SpecialLabels below]) .
+
+This document also suggests alternatives and approaches to implement some 
+features defined in 
+[wiki:TracDev/Proposals/MultipleProject Multi-Project Support for Trac]. Some 
+content may actually overlap aforementioned specification.
+
+== URL space for different projects == #UrlMapping
+
+A constraint should be imposed in order to simplify dispatching strategy so as 
+to map projects to ''URL''s. Project short name '''MUST''' be unique in the 
+context of an environment. 
+
+  - '''host mapping''': the name of the (virtual) host used to access the 
+    ''Trac'' environment is taken to be the name of the project. A given host 
+    can be configured to be an alias for the default, top-level project. Label 
+    names are not allowed to be used this way.
+  - '''prefix mapping''': if the `PATH_INFO` starts with `/p/<project name>/` 
+    prefix, name of a project will be taken to be `<project_name>` . Otherwise if 
+    it starts with `/l/<label_name>/` then the request is addressed to the set 
+    of projects included in label `<label_name>`. In general this is less 
+    ambiguous than the 
+    [wiki:TracDev/Proposals/MultipleProject#URLspacefordifferentprojects mapping suggested in original proposal].
+    Explanation and implementation details provided [#UrlExplained below].
+
+== The Data Model and the API == #DataModelApi
+
+Labels may be considered as resources bound to the environment rather 
+than to particular projects (e.g. like `Changeset` and `Source` which belong 
+to a given repository - see MultiRepos). Hence only an 
+additional `labels` table is also needed, and it can take the form of a 
+''resource table specialization'' from the GenericTrac. Project labels should 
+have at least short name (and maybe description) field. Project labels can be 
+linked explicitly to projects and labels (if using [#NestedLabels nested labels]).
+These connections can take the form of ''relations'' from 
+[wiki:TracDev/Proposals/TracRelations Trac Relations].
+
+=== URL prefix mapping explained === #UrlExplained
+
+Project-specific URLs will start with `/p/<project name>` prefix. 
+Requests involving multiple projects will be made available on a per-label 
+basis at ''URL''s starting with `/l/<label name>` prefix. Remaining path after 
+this will be used to select what instance of `IRequestHandler` should process 
+the request. Examples below illustrate some use cases. In all cases  
+multi-project environment root ''URL'' is `http://server.com/path/to/trac/` and 
+it will contain the reference project hierarchy used throughout this document :
+
+|| '''URL''' || '''Target projects''' || '''Comments''' ||
+|| `http://server.com/path/to/trac/` || top-level project (i.e. `''` ) ||  || 
+|| `http://server.com/path/to/trac/roadmap` || top-level project (i.e. `''` ) || Top-level milestone view. This may be used to show top-level (e.g. product, current year, ...) milestones. || 
+|| `http://server.com/path/to/trac/p/FamilyB/roadmap` || project '''FamilyB''' || '''FamilyB''' project-specific milestones. || 
+|| `http://server.com/path/to/trac/p/product_c/roadmap` || project '''product_c''' || '''product c''' project-specific milestones. || 
+|| `http://server.com/path/to/trac/l/javascript/roadmap` || all projects in label '''javascript''' || display milestones for javascript projects. || 
+
+By doing things this way request dispatch may be implemented as a combination of 
+two existing architectural features , namely '''request filters''' and 
+'''request handlers'''. First of all by supporting multi-project 
+specifications the context associated to the request has to contain 
+information about target project(s) . One component acting as a request filter  
+intercepts the request before match is performed. If any multiproject 
+prefix (i.e. `/p/<project name>` or `/l/<label name>`) is detected then 
+project resolution takes place. Single-project requests only 
+need to add corresponding internal project resource to context. 
+In the case of labels the context should contain ''label name'' as well as a 
+list of resources identifying target projects . In the case of 
+[#SpecialLabels more complex project selector expressions] the context should contain the 
+expression itself, the instance of `IProjectLabelManager` matching label name, 
+and the list of resource objects identifying target projects . If this 
+advanced feature will be supported, it may be considered as a generic way to 
+encapsulate multi-project context in spite of having flexibility and uniformity, 
+considering the fact that first two variants are just particular cases. 
+Aforementioned data may be retrieved right away at dispatch time or loaded 
+on demand.
+
+Immediately after multi-project context resolution, the request filter rewrites 
+`PATH_INFO` by removing project selection prefix. The request is then 
+matched as usual so as to determine the handler responsible for processing it 
+(e.g. `wiki`, `ticket`, ...). The target instance of `IRequestHandler` will 
+rely on request context so as to determine target projects involved and 
+build the response accordingly.
+
+== Advanced labels features == #LabelsAdvanced
+
+Subsequent sub-sections deal with some advanced features that may be useful 
+under certain circumstances but may also over-complicate core design . 
+Nonetheless I mention them here for the sake of 
+~~could not find the right word~~.
+
+=== Project alias === #LabelAlias
+
+A label related to a single project may be considered a project alias. This 
+scenario may happen when two or more projects are merged and previous project 
+name is to be kept so as not to break external references, for instance.
+
+=== Nested labels === #NestedLabels
+
+It might be convenient as well to provide a way to specify a hierarchy of 
+labels (rather than projects). In order to illustrate this with a particular 
+example which might be very common in practice, let's consider we have the 
+[wiki:TracDev/Proposals/MultipleProject#ProjectTree sample hierarchy of projects] 
+and still need to 
+group them according to programming languages and frameworks used to build 
+them (let them be explicit project dependencies or not). In that case it will 
+be useful to have some labels like `javascript`, `python`, `c#`, `vb.net`, 
+`f#`, `ruby`, `php` and so on. Let's also consider a similar situation 
+and project classification also includes frameworks, so there are further 
+tags like e.g. `trac`, `wcf`, `jquery`, `mootools`, `wpf`, `django`, `dojo`, ... 
+Nonetheless :
+
+  - It may be useful to know which projects are related to ''.NET framework''.
+  - It may be useful to ease the process by tagging projects using a single 
+    label identifying a framework and having them auto-magically included in 
+    the label for the corresponding programming language .
+
+In order to do that the following label hierarchy might help :
+
+{{{
+ +-- python
+ | +-- trac
+ | +-- django
+ +-- ruby
+ +-- javascript
+ | +-- jquery
+ | +-- dojo
+ | +-- mootools
+ +-- .net
+ | +-- .net languages
+ | | +-- c#
+ | | +-- vb.net
+ | | +-- f#
+ | +-- .net technologies
+ | | +-- wpf
+ | | +-- wcf
+ | | +-- wwf
+ +-- php
+ 
+}}}
+
+For instance , [http://trac-hacks.org Trac-Hacks] website may be one such 
+example where there's a flat one-level project hierarchy and labels to group 
+hacks. In [#TracHacksLabels Apendix B] it is possible to see 
+sample label hierarchy based on hack classifiers available at present. Idea
+is , for instance, that if somebody tags a project using `macro` label then 
+it also belongs auto-magically in `plugins` label. 
+
+There's another precision that needs to be mentioned up to this point and it 
+is whether it is more convenient to define label relationships using graphs 
+rather than a tree . Considering the same case mentioned above , 
+labels like `iron_python` , `iron_ruby` would be hard to 
+classify considering aforementioned hierarchy as they may be related to both 
+`.net` and (`python` | `ruby`) (same reasoning for e.g. `jpype` , `jython` for 
+`python` & `java`; `rython` , `unholy` for `python` & `ruby` ... and it's 
+possible to find more examples even in totally different business domains).
+
+=== Project context extensions === #SpecialLabels
+
+It may be useful to be able to specify ''special'' project groups like :
+
+  - ''all parents of project A''
+  - ''direct children of project B''
+  - ''descendant of project C'' 
+  - `*` all the projects (mentioned in [wiki:TracDev/Proposals/MultipleProject#URLspacefordifferentprojects original Multi-Project specification])
+  - glob pattern (mentioned in [wiki:TracDev/Proposals/MultipleProject#URLspacefordifferentprojects original Multi-Project specification])
+  - `!` prefix to exclude projects (mentioned in [wiki:TracDev/Proposals/MultipleProject#URLspacefordifferentprojects original Multi-Project specification])
+  - comma-separated list of project names (e.g. `FamilyA,product_d,3rdParty`)
+  - ''XPath expressions''
+
+These are just a few examples. In order to prepare the system for flexibilty 
+and maybe allow the definition of other project selector expressions (e.g. in 
+plugins) it is convenient to introduce a new interface 
+(namely `IProjectLabelManager`) used to determine which projects belong in a 
+given label, provided its name. Selection should work using a chain of 
+responsibilty similar to the one already used for `IRequestHandler`. All 
+instances of `IProjectLabelManager` are requested to expand a project selector 
+expression. This will consist of returning a list of project names ''matching'' 
+a given label name (aka ''project selector expression'' <= this seems to be 
+more generic ''';)''' , or `None` if such match is not found. In the later case 
+the next instance of `IProjectLabelManager` is considered and so on ... until 
+either a match is found (and subsequent request handling takes place) or all 
+options are exhausted (and error handling occurs e.g. ''HTTP 404 Not Found'' 
+returned to the client) . 
+
+== User interface == #LabelsGUI
+
+Considering everything mentioned up to this point , the following variants of
+project selector GUI control are suggested.
+
+=== Project selector (drop-down menu) === #LabelsMenu
+
+The use of labels makes possible to present a flat drop-down menu to the user 
+in order to select a set of projects like shown below. This may be considered 
+more appropriate than always having to display a hierarchy.
+
+{{{
+#!html
+
+<select id="SampleProjectMenu" name="field_milestone">
+  <option></option>
+  <optgroup label="Projects">
+    <option>Top-level</option>
+    <option>Family A</option>
+    <option>&nbsp;&nbsp;product a</option>
+    <option>&nbsp;&nbsp;product b</option>
+    <option>Family B</option>
+    <option>&nbsp;&nbsp;product c</option>
+    <option>&nbsp;&nbsp;product d</option>
+    <option>Tools</option>
+    <option>3rdParty</option>
+  </optgroup>
+  <optgroup label="Labels">
+    <option>Product families</option>
+    <option selected="true">Products</option>
+    <option><i>Create new label ...</i></option>
+  </optgroup>
+</select>
+}}}
+
+'''PS''': ''Create new label ...'' option should be visible only if user can 
+create labels. If the user can modify labels (i.e. classify projects in 
+categories) then it may be useful to include shortcut links to update projects 
+membership. In both cases a dialog (see picture below) should be displayed.
+
+{{{
+#!html
+
+<div id="SampleLabelsEditor" style="width:50%;margin-left:auto;margin-right:auto;background-color:#666666;">
+  <div style="background-color:#666666;color:#ffffff;">Create new label</div>
+  <div style="background-color:#ffffff;padding:15px;">
+   <label for="label_id">Label ID :</label>
+   <input type="text" id="label_id"></input>
+   <br/>
+   <label for="label_name">Label name :</label>
+   <input type="text" id="label_name"></input>
+   <br/>
+   <fieldset style="display: inline;clear:both;">
+    <legend>Select projects</legend>
+    <form>
+     <ul style="list-style-type: none">
+      <li>
+      <input type="checkbox">Top-level</input>
+      <ul style="list-style-type: none">
+       <li>
+        <input type="checkbox" checked="checked"><b>Family A</b></input>
+        <ul style="list-style-type: none">
+         <li><input type="checkbox">product a</input></li>
+         <li><input type="checkbox">product b</input></li>
+        </ul>
+       </li>
+       <li>
+        <input type="checkbox" checked="checked"><b>Family B</b></input>
+        <ul style="list-style-type: none">
+         <li ><input type="checkbox">product c</input></li>
+         <li><input type="checkbox">product d</input></li>
+        </ul>
+       </li>
+       <li><input type="checkbox">Tools</input></li>
+       <li><input type="checkbox">3rdParty</input></li>
+      </ul>
+      </li>
+     </ul>
+    </form>
+   </fieldset>
+   <br/>
+   <button>Ok</button>
+   <button>Cancel</button>
+  </div>
+</div>
+}}}
+
+=== Project selector (tree view) === #LabelsTreeView
+
+Another option is to provide a more ellaborate version of the box suggested in 
+[wiki:TracDev/Proposals/MultipleProject Multi-Project Support specification]. 
+One of the benefits is that it will be possible to select either projects or 
+labels. It should look like this 
+
+{{{
+#!html
+<fieldset style="display: inline" id="SampleProjectTreeView">
+ <legend>Project Selector</legend>
+ <form>
+  <ul style="list-style-type: none">
+   <li>
+    <input type="checkbox">Top-level</input>
+    <ul style="list-style-type: none">
+     <li>
+      <input type="checkbox"><b style="background-color: #ffffcc;border:1px dashed #999999;">Family A</b></input>
+      <ul style="list-style-type: none">
+       <li><input type="checkbox">product a</input></li>
+       <li><input type="checkbox">product b</input></li>
+      </ul>
+     </li>
+     <li>
+      <input type="checkbox"><b style="background-color: #ffffcc;border:1px dashed #999999;">Family B</b></input>
+      <ul style="list-style-type: none">
+       <li ><input type="checkbox">product c</input></li>
+       <li><input type="checkbox">product d</input></li>
+      </ul>
+     </li>
+     <li><input type="checkbox">Tools</input></li>
+     <li><input type="checkbox">3rdParty</input></li>
+    </ul>
+   </li>
+  </ul>
+  <ul style="list-style-type: none">
+   <li style="background-color: #999999; color: #ffffff">
+    <input type="checkbox" checked="checked"><b>Product families</b><a href="#SampleProjectTreeView" style="font-size:11px;margin-left:3px;">Edit</a></input>
+   </li>
+   <li style="background-color: #CCCCCC">
+    <input type="checkbox">Products<a href="#SampleProjectTreeView" style="font-size:11px;margin-left:3px;">Edit</a></input>
+   </li>
+   <li style="background-color: #999999; color: #ffffff">
+    <input type="checkbox"><b>All except product b</b><a href="#SampleProjectTreeView" style="font-size:11px;margin-left:3px;">Edit</a></input>
+   </li>
+   <li>  <button>New label ...</button> </li>
+  </ul>
+ </form>
+</fieldset>
+}}}
+
+Once label is selected then target projects should be highlighted like above.
+
+Ideally it should be possible to drag a project & drop it on an item 
+representing a label in order to add that project to that label (a confirmation 
+box may be shown so as to detect mistakes).
+
+Label membership editor dialog box may be displayed as well so as to edit a 
+label if user clicks on ''Edit'' link.
+
+== Appendix A : Other systems supporting labels == #SimilarSystems
+
+Other similar examples of the use of labels in other products are :
+
+  - [http://support.google.com/plus/bin/answer.py?hl=en&answer=1047805&topic=1257347&ctx=topic Google+ circles] which allow to group people, 
+  - ''GMail contact groups'' which serve to a similar purpose
+  - ''GMail labels'' which allow to mark e-mails 
+
+Other instances of similar label hierarchies :
+
+  - ''GMail'' nested labels.
+
+== Appendix B : Proposed label hierarchy for Trac-Hacks == #TracHacksLabels
+
+This section considers just a subset of 
+[http://trac-hacks.org Trac-Hacks] classifiers.
+
+{{{
+
+ +-- supported-version
+ | +-- 0.1
+ | +-- 0.10
+ | +-- 0.10.4
+ | +-- 0.11
+ | +-- 0.11.5
+ | +-- 0.11.6
+ | +-- 0.12
+ | +-- 0.12-compatible
+ | +-- 0.12dev
+ | +-- 0.13
+ | +-- 0.3.4
+ | +-- 0.4
+ | +-- 0.5
+ | +-- 0.5dev
+ | +-- 0.8
+ | +-- 0.9
+ | +-- 0.9.1
+ | +-- 0.9.2
+ | +-- 0.9.6
+ | +-- 1.1dev
+ | +-- trunk
+ | +-- anyrelease
+ +-- db
+ | +-- sql
+ | +-- sqlalchemy
+ | +-- sqlite
+ | | +-- sqlite3
+ | +-- postgresql 
+ | +-- mysql
+ +-- plugin
+ | +-- macro
+ | +-- theme
+ +-- scripts
+ +-- patch
+ +-- integration
+ +-- translation
+ +-- workflow
+
+}}}