Changes between Version 48 and Version 49 of TracJsGanttPlugin


Ignore:
Timestamp:
Jun 6, 2014, 2:16:47 PM (8 years ago)
Author:
Chris Nelson
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • TracJsGanttPlugin

    v48 v49  
    99Configurable field names allow integration with other plugins such as MasterTicketsPlugin (for dependencies), SubticketsPlugin (for parent/child relationships) and TimingAndEstimationPlugin (for estimated and total hours).
    1010
     11Over 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.
     12
    1113== Usage ==
    1214
     
    1416
    1517[[Image(jsGanttSample.PNG)]]
     18
     19`[[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`.)
     20
     21`[[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`.)
     22
     23`[[TracJSGanttChart(scheduled=1,display=owner:chrisn)]]` find all the scheduled tickets and display only those owned by user `chrisn`.
     24
    1625
    1726=== Arguments ===
     
    4958Site-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.
    5059
    51 All other macro arguments are treated as TracQuery specification (e.g., milestone=MS1|MS2) to control which tickets are displayed.
     60All other macro arguments are treated as TracQuery specification (e.g., `milestone=MS1|MS2`) to control which tickets are displayed.
    5261
    5362== Interfaces ==
     
    121130  * `hoursAvailable()` returns 8 for Monday through Friday and 0 for Saturday and Sunday.
    122131
    123 An adapter to interface TeamCalendarPlugin` with TracPM is underdevelopment.
     132TeamCalendarPlugin provides an implementation which returns 0 hours for any day that a developer is marked unavailable in the calendar.
    124133
    125134=== ITaskScheduler ===
    126135
    127136An interface for task schedulers exists but it not yet well documented.
     137
     138{{{
     139#!py
     140class ITaskScheduler(Interface):
     141    # Schedule each the ticket in tickets with consideration for
     142    # dependencies, estimated work, hours per day, etc.
     143    #
     144    # Assumes tickets is a list returned by TracPM.query().
     145    #
     146    # On exit, each ticket has a start and finish that can be accessed
     147    # with TracPM.start() and finish().  No other changes are made.
     148    def scheduleTasks(self, options, tickets):
     149        """Called to schedule tasks"""
     150}}}
     151
     152== Scheduling ==
     153
     154If the `TicketRescheduler` module is enabled, `TracPM` maintains private tables with task scheduling information. The `schedule` table has the current schedule:
     155
     156{{{
     157 Column |  Type   | Modifiers
     158--------+---------+-----------
     159 ticket | integer | not null
     160 start  | bigint  |
     161 finish | bigint  |
     162Indexes:
     163    "schedule_pkey" PRIMARY KEY, btree (ticket)
     164    "schedule_ticket_idx" btree (ticket)
     165}}}
     166
     167The `schedule_change` table holds a record of changes in the schedule over time.
     168
     169{{{
     170  Column   |  Type   | Modifiers
     171-----------+---------+-----------
     172 ticket    | integer | not null
     173 time      | bigint  | not null
     174 oldstart  | bigint  |
     175 oldfinish | bigint  |
     176 newstart  | bigint  |
     177 newfinish | bigint  |
     178Indexes:
     179    "schedule_change_pk" PRIMARY KEY, btree (ticket, "time")
     180    "schedule_change_ticket_idx" btree (ticket)
     181    "schedule_change_time_idx" btree ("time")
     182}}}
     183
     184It 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.
     185
     186These tables are maintained by a ticket change listener which looks for changes to fields which might affect schedule then:
     187
     188 * identifies all tickets that were active (required for an open milestone or an active ticket of the configured milestone ticket type)
     189 * identifies all tickets that are now active (as a result of the changes)
     190 * removes any tickets that were active but are no longer from `schedule` (updating the history in `schedule_change`)
     191 * runs the scheduling algorithm on all tickets that are now active
     192 * writes any changes to `schedule` (updating history in `schedule_change`)
     193
     194With 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.
     195
     196{{{
     197#!sql
     198SELECT
     199   p.value AS __color__,
     200   t.id AS ticket,
     201   summary,
     202   priority,
     203   description as _description,
     204   est.value as est,
     205   act.value as act,
     206   -- This bit is specific to Postgres.
     207   (SELECT to_date(to_timestamp((sched.finish/1000000))::text,
     208                                'YYYY-MM-DD')) AS due,
     209   status
     210FROM ticket AS t
     211INNER JOIN schedule AS sched ON (t.id=sched.ticket)
     212INNER JOIN enum AS p ON (p.name=t.priority AND p.type = 'priority')
     213LEFT OUTER JOIN ticket_custom AS est ON
     214     (t.id=est.ticket AND est.name='estimatedhours')
     215LEFT OUTER JOIN ticket_custom AS act ON
     216     (t.id=act.ticket AND act.name='totalhours')
     217WHERE t.owner = '$USER' AND status <> 'closed'
     218ORDER BY due NULLS FIRST, p.value
     219}}}
    128220
    129221== Installation ==