Changes between Version 48 and Version 49 of TracJsGanttPlugin

Timestamp:

Jun 6, 2014, 2:16:47 PM (10 years ago)

Author:

Chris Nelson

Comment:

Documented more usage cases, some missing interfaces, and use of the background rescheduler

TracJsGanttPlugin

@@ -9 +9 @@
 Configurable field names allow integration with other plugins such as MasterTicketsPlugin (for dependencies), SubticketsPlugin (for parent/child relationships) and TimingAndEstimationPlugin (for estimated and total hours).
 
+Over time, the project management aspects of the Gantt chart have been isolated in the `TracPM` module which has grown to include a query helper (which allows finding tickets based on dependencies) and a ticket change listener (which reschedules tickets based on various constraints) and other support functions.  Ultimately, these features -- which really have nothing to do with the Gantt chart -- will be moved to a separate `TracPM` plugin.
+
 == Usage ==
 
@@ -14 +16 @@
 
 [[Image(jsGanttSample.PNG)]]
+
+`[[TracJSGanttChart(goal=1234,schedule=asap)]]` finds all the tickets required for ticket 1234 (by following the Required For dependency) and schedules them As Soon As Possible.  (In a ticket description or comment, the ticket ID may be replaced by `self`.)
+
+`[[TracJSGanttChart(root=self)]]` (when used in a ticket description or comment) finds all the tickets which are descendants of the current ticket (by following the parent/child relationship) and scheduled them As Late As Possible (the default algorithm). (`self` can be replaced by one or more pipe-delimited ticket IDs as for the `id` option, e.g., `root=1|3|5|9`.)
+
+`[[TracJSGanttChart(scheduled=1,display=owner:chrisn)]]` find all the scheduled tickets and display only those owned by user `chrisn`.
+
 
 === Arguments ===
@@ -49 +58 @@
 Site-wide defaults for macro arguments may be set in the `[trac-jsgantt]` section of `trac.ini`. Where `option.<opt>` overrides the built-in default for `<opt>` from the table above.
 
-All other macro arguments are treated as TracQuery specification (e.g., milestone=MS1|MS2) to control which tickets are displayed.
+All other macro arguments are treated as TracQuery specification (e.g., `milestone=MS1|MS2`) to control which tickets are displayed.
 
 == Interfaces ==
@@ -121 +130 @@
   * `hoursAvailable()` returns 8 for Monday through Friday and 0 for Saturday and Sunday.
 
-An adapter to interface TeamCalendarPlugin` with TracPM is underdevelopment.
+TeamCalendarPlugin provides an implementation which returns 0 hours for any day that a developer is marked unavailable in the calendar.
 
 === ITaskScheduler ===
 
 An interface for task schedulers exists but it not yet well documented.
+
+{{{
+#!py
+class ITaskScheduler(Interface):
+    # Schedule each the ticket in tickets with consideration for
+    # dependencies, estimated work, hours per day, etc.
+    #
+    # Assumes tickets is a list returned by TracPM.query().
+    #
+    # On exit, each ticket has a start and finish that can be accessed
+    # with TracPM.start() and finish().  No other changes are made.
+    def scheduleTasks(self, options, tickets):
+        """Called to schedule tasks"""
+}}}
+
+== Scheduling ==
+
+If the `TicketRescheduler` module is enabled, `TracPM` maintains private tables with task scheduling information. The `schedule` table has the current schedule:
+
+{{{
+ Column |  Type   | Modifiers 
+--------+---------+-----------
+ ticket | integer | not null
+ start  | bigint  | 
+ finish | bigint  | 
+Indexes:
+    "schedule_pkey" PRIMARY KEY, btree (ticket)
+    "schedule_ticket_idx" btree (ticket)
+}}}
+
+The `schedule_change` table holds a record of changes in the schedule over time.
+
+{{{
+  Column   |  Type   | Modifiers 
+-----------+---------+-----------
+ ticket    | integer | not null
+ time      | bigint  | not null
+ oldstart  | bigint  | 
+ oldfinish | bigint  | 
+ newstart  | bigint  | 
+ newfinish | bigint  | 
+Indexes:
+    "schedule_change_pk" PRIMARY KEY, btree (ticket, "time")
+    "schedule_change_ticket_idx" btree (ticket)
+    "schedule_change_time_idx" btree ("time")
+}}}
+
+It is possible -- but not yet supported -- to use the data in `schedule_change` to reconstruct a baseline schedule for an effective date and then report changes from that baseline.
+
+These tables are maintained by a ticket change listener which looks for changes to fields which might affect schedule then:
+
+ * identifies all tickets that were active (required for an open milestone or an active ticket of the configured milestone ticket type)
+ * identifies all tickets that are now active (as a result of the changes)
+ * removes any tickets that were active but are no longer from `schedule` (updating the history in `schedule_change`)
+ * runs the scheduling algorithm on all tickets that are now active
+ * writes any changes to `schedule` (updating history in `schedule_change`)
+
+With this data in place, you can show a Gantt of scheduled tickets with dates as in the database (`[[TracJSGanttChart(scheduled=1)]]`) or create reports of the scheduled tickets.
+
+{{{
+#!sql
+SELECT 
+   p.value AS __color__, 
+   t.id AS ticket, 
+   summary, 
+   priority, 
+   description as _description,
+   est.value as est, 
+   act.value as act, 
+   -- This bit is specific to Postgres.
+   (SELECT to_date(to_timestamp((sched.finish/1000000))::text,
+                                'YYYY-MM-DD')) AS due,
+   status
+FROM ticket AS t
+INNER JOIN schedule AS sched ON (t.id=sched.ticket)
+INNER JOIN enum AS p ON (p.name=t.priority AND p.type = 'priority')
+LEFT OUTER JOIN ticket_custom AS est ON
+     (t.id=est.ticket AND est.name='estimatedhours')
+LEFT OUTER JOIN ticket_custom AS act ON
+     (t.id=act.ticket AND act.name='totalhours')
+WHERE t.owner = '$USER' AND status <> 'closed' 
+ORDER BY due NULLS FIRST, p.value
+}}}
 
 == Installation ==