[[PageOutline(2-5,Contents,pullout)]]

= Add pseudo child-tickets and a visual reference to these within a parent ticket

== Description

This plugin modifies the ticket description box and adds a child ticket listing table and a 'create' button for adding new child tickets.

Having child-tickets is useful when multiple releases need to be managed. For example for a single 'bug-report' ticket and a single 'bug-fix' ticket for each milestone/branch of development, for managing sub-tasks of an issue and for managing 'bug-fixes' required when developing a new (larger) enhancement.

It is possible to control in trac.ini the following aspects of child-ticket creation/viewing:
 * allow/disallow child-tickets for a certain type of ticket
 * define the table headers displayed in the parent ticket
 * define a default for the child type to be created / restrict the type of child-tickets
 * define which fields are inherited by child-tickets

[[Image(NewChildTicketTable.png, border=2)]]

This and other examples of this plugin can be found [wiki:ChildTicketsPlugin/Examples here]. 

=== Background

Some time ago I came across the problem of how to manage child tickets in a meaningful fashion, we were using [wiki:coderanger]'s original [wiki:MasterTicketsPlugin] and it was great until we started to allow tickets to be viewed and created by people outside of our immediate development group. We found that people who were not familiar with our processes would simply create child tickets of the wrong 'type' and needed some help in getting it right. In addition, users found that the lack of visual information (ie. what are this tickets child tickets?) was also a hindrance.

Under Trac 0.10 I had to modify the ticket.html templates to get this working in any 'pretty' sense so I have not provided support for 0.10. As of 0.11, the ITemplateStreamFilter allows this to be incorporated nicely into a neat plugin.

To keep the plugin compact and simple and to allow future compatibility with different CSS schemes, I have simply 'pinched' the existing CSS classes for generating the table and its components.

'''Note''': The configurability of this plugin has been ported to the SubticketsPlugin. See the patches in issues 9-12 at [https://github.com/itota/trac-subtickets-plugin/issues github]. -- Chris Nelson

== Bugs/Feature Requests

Existing bugs and feature requests for ChildTicketsPlugin are 
[report:9?COMPONENT=ChildTicketsPlugin here].

If you have any issues, create a 
[/newticket?component=ChildTicketsPlugin new ticket].

[[TicketQuery(component=ChildTicketsPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:childticketsplugin here].

== Source

You can check out ChildTicketsPlugin from [/svn/childticketsplugin here] using Subversion, or [source:childticketsplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Configuration

The plugin makes use of the 'ticket-custom' field and so requires no extra database tables to be created. The following fields are required in the `trac.ini` file:

{{{#!ini
[components]
childtickets.* = enabled

[ticket-custom]
parent = text
parent.format = wiki
parent.label = Parent ID

[childtickets]
# 'enhancements': child tickets will typically be bug-fix tickets with the same milestone, component and keywords.
parent.enhancement.allow_child_tickets = true
parent.enhancement.restrict_child_type = bug-fix, task
parent.enhancement.table_headers = type, status, owner, summary
parent.enhancement.inherit = milestone, component, keywords

# 'bug-report': child tickets will typically be bug-fix
parent.bug-report.allow_child_tickets = true
parent.bug-report.default_child_type = bug-fix
parent.bug-report.table_headers = type, priority, owner, summary, milestone
parent.bug-report.inherit = component, keywords

# 'issue': child tickets will typically be task tickets with no default milestone.
parent.issue.allow_child_tickets = true
parent.issue.restrict_child_type = task
parent.issue.table_headers = type, status, owner, summary, milestone

# 'bug-fix': child tickets are not allowed.
parent.bug-fix.allow_child_tickets = false

# 'task': child tickets are not allowed.
parent.task.allow_child_tickets = false
}}}

See table below for a generic description of the options.

=== [childtickets]

{{{#!html
<table class="wiki">
<tr><td><b>Field</b></td><td><b>Description</b></td><td><b>Default value</b></td></tr>
<tr><td width=20%>parent.<b><i>parent-type</i></b>.allow_child_tickets </td><td> Define whether child tickets are allowed or not </td><td> False</td></tr>
<tr><td width=20%> parent.<b><i>parent-type</i></b>.table_headers </td><td> List of column headers for display in parent ticket </td><td> summary, owner </td></tr>
<tr><td width=20%> parent.<b><i>parent-type</i></b>.default_child_type </td><td> Default child type </td><td>See [ticket] section of trac.ini (default_type) </td></tr>
<tr><td width=20%> parent.<b><i>parent-type</i></b>.restrict_child_type </td><td> A list of possible child types, trying to create a child of a different 'type' will create an error. As of version 1.1.0, if this option is used, a list of submit buttons will be rendered allowing the user to decide which type of child ticket he/she wants to create. </td><td>None </td></tr>
<tr><td width=20%> parent.<b><i>parent-type</i></b>.inherit </td><td> Define a list of inherited fields. </td><td> Default: None </td></tr>
<tr><td width=20%> default.max_depth</td><td> Limit the creation of too deep a hierarchy. </td><td>5</td></tr>
</table>
}}} 

== Known Issues / Caveats

 * If you change the behaviour of the parent type (using for example allow_child_tickets/restrict_child_type) and tickets already have child tickets assigned to them, you will not receive a warning about any possible conflicts until you try and modify any of the child tickets.
 * If a parent ticket is restricted in some way that no further child tickets can be generated for that ticket 'type', you'll continue to see a list of child tickets but the 'Create' button will be missing.
 * The 'parent.<type>.inherit' option ensures fields are inherited by child tickets. However, all child tickets regardless of type as defined by 'restrict_child_type' will inherit these values.

== Recent Changes

[[ChangeLog(childticketsplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:walnut] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''