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

= Subtickets support for Trac tickets

== Description

This plugin offers a sub-ticket feature for managing tickets. Subtickets are useful for when several tickets are developed and released under one master ticket. The master ticket in the example below called the Root ticket, has multiple subtickets defined under it.

The following screenshot demonstrates how the subtickets are displayed below the Description section of a ticket:

[[Image(trac-subtickets-plugin_001.png)]]

Relations between tickets are stored in a table called `Subtickets` with just two columns: ''parent'', ''child'' and that eases reporting considerably when compared to ChildTicketsPlugin. For further information on reporting, see SubticketsPlugin/Reporting.

Since tickets can have multiple parents, the expressive power of SubticketsPlugin corresponds to that of MasterTicketsPlugin (ie. both allow tickets to be organised in an acyclic directed graph). The UI of MasterTicketsPlugin is mostly oriented towards linking up already-existing tickets while SubticketsPlugin's UI is mostly oriented towards top-down creation and inspection of a ticket hierarchy.

== Bugs/Feature Requests

Existing bugs and feature requests for SubticketsPlugin are [https://github.com/trac-hacks/trac-subtickets-plugin/issues here].

If you have any issues, create a [https://github.com/trac-hacks/trac-subtickets-plugin/issues new issue].

== Download

You can download zipped source from [https://github.com/trac-hacks/trac-subtickets-plugin/zipball/master here].

== Source

You can check out the source for SubticketsPlugin from [https://github.com/trac-hacks/trac-subtickets-plugin.git here] using Git, or browse the source with [https://github.com/trac-hacks/trac-subtickets-plugin GitHub].

== Installation

 1. Download the [https://github.com/trac-hacks/trac-subtickets-plugin/zipball/master zip file], unpack it and run:
 {{{#!sh
python setup.py bdist_egg
 }}}
 1. Install it in one of the following ways:
  {{{#!sh
cp dist/*.egg path/to/trac/env/plugins
 }}}
  {{{#!sh
easy_install dist/*.egg
 }}}
  {{{#!sh
python setup.py install
 }}}
 1. Enable the plugin in your `trac.ini` file as follows:
 {{{#!ini
[components]
tracsubtickets.api.* = enabled
tracsubtickets.web_ui.* = enabled
 }}}
 1. Upgrade your Trac environment:
 {{{#!sh
trac-admin <env> upgrade
 }}}


For Trac 1.4, include Genshi in the requirements.

== Configuration

This plugin shares some of the configurations with ChildTicketsPlugin. Most settings are ticket type dependent, such as `defect` and `task` in the example below:
{{{#!ini
# Select column headings in child listing
# Id and summary are always displayed
type.defect.table_columns = priority,keywords,owner
type.task.table_columns   = # display id and summary only

# Control which fields are inherited from parent to child when creating child
type.defect.child_inherits = keywords,milestone
type.task.child_inherits   = version,cc

# Control the visual appearance of the create subticket link. Config value shall be one of "button" and "link"
add_style = button

# Enable ticket modification (except comments) when a parent is closed (default=true)
no_modif_when_parent_closed = false

# Normally SubticketsPlugin will refuse closing parents when a child is non-closed and similarly
# reopening a child whose parent is closed. These behaviours can be suppressed by adding 
# either of the action names tho this setting:
skip_closure_validation = resolve,reopen

# The number of child levels is controlled by the following setting, where 
# -1 (default) means infinity and zero means one level of children.
recursion_depth = 2    # - three levels of children

}}}

If IniAdminPlugin is installed, the configuration can be edited through the administration panel `subtickets`. The plugin detects which ticket types are defined and creates config values accordingly. Config values are ''not'' deleted when ticket types are deleted and they will disappear from the admin panel only when trac is restarted. Also note that as long as a config value is not changed wrt. its hardcoded default value, it is not added to `trac.ini`.

=== Incompatibilities with earlier versions

'''With <= 0.4.1:''' In order to obtain a not-too-unreasonable sorting of config values in the admin panel, all ticket type-specific config values now have the prefix `type.`

== Interaction with ticket workflows

If the ticket workflow includes actions `resolve` and `reopen`, they will block and show an error message when:
 * trying to `resolve` a ticket with one or more non-`closed` children
 * trying to `reopen` or modify fields of a `closed` ticket with one or more `closed` parents.

This behaviour can be inhibited; see above.

== Interaction with XmlRpcPlugin

Parent/child relationships can be managed through XmlRpcPlugin: Simply update the `parents` attribute with a comma-separated list of parent ticket ids.

== About i18n/l10n support

This plugin is prepared for localization. The patched version is available at the Git repo now.

The English message texts are still the (POSIX) default. If this isn't your preferred language, you can:
 1. check if it is already available from the [TracPluginTranslation Trac plugin l10n project] at [https://www.transifex.com/projects/p/Trac_Plugin-L10N/resource/tracsubtickets Transifex] or
 2. do it yourself, see the [t:CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details.

Contributing your translation is highly appreciated! You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project] via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]:

Top translations: Trac_Plugin-L10N » [https://www.transifex.com/projects/p/Trac_Plugin-L10N/resource/tracsubtickets tracsubtickets][[BR]]
 [[Image(http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracsubtickets/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracsubtickets/)]]

== Author/Contributors

'''Author:''' [wiki:itota] [[BR]]
'''Maintainer:''' [wiki:thenor] [[BR]]
'''Contributors:''' [wiki:hasienda], [wiki:ChrisNelson], [https://github.com/roandbox Andrei Rodionov] (Russian x-lation)