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

= Manage relations between Trac resources like ''relates to'' or ''parent > child'' in tickets

== Description

This plugin provides a general system for relating different Trac resources. The kind of resource is dependend on the use case.

It comes with plugins for relations between tickets with the following **link types**:
* simple relations between tickets without any special semantics ({{{relates to}}})
* allow a ticket to {{{block}}} another ticket
* specify {{{parent -> child}}} relationships similar to what can be found in the ChildTicketsPlugin.
* {{{duplicate}}} tickets

The relations are saved in the database and can be used in reports.

=== Enhanced ticket page
* The plugin adds the relationship information to the ticket properties box when a ticket page is shown.
* Manage relations between tickets from the ticket page using a popup dialog.
* Buttons for direct creation of child tickets of different types.
* When child tickets exist for a ticket they are shown as a tree below the properties box.

=== Duplicate tickets
When resolving a ticket as a duplicate the user may input a ticket number and a {{{duplicate}}} relation is automatically created.


=== Blocking tickets
Ticket validator checks for {{{blocked}}} tickets:
  * Disallowing closing of a ticket when open blocking tickets exist
  * Detecting loops in your dependencies
  * Making sure a blocked or blocking ticket actually exists

=== Child tickets

* Child tickets may have one or several parents
* Show a child ticket tree with proper indentation and configurable depth
* Ticket validator checks for:
  * Disallowing closing of parents when open children exist
  * Detecting loops in your dependencies
  * Making sure a parent ticket actually exists
* Allow/disallow child-tickets for a certain type of ticket
* Define the table headers displayed in the child ticket depending on the type
* Define a default for the child type to be created
* Restrict the type of possible child-tickets for each parent ticket type
* Define which fields are inherited by child-tickets

There are admin pages available for configuring the features but it is also possible to control them by settings in trac.ini. See the configuration section for more info.

=== Other plugins

[[ListTagged(dependency plugin)]]

== Screenshots
{{{#!box width=500
==== Relation properties
[[Image(childrelations_properties.png, border=1, width=480)]]
}}}

{{{#!box width=350
==== Modify relations form the ticket page
[[Image(child_relations_modify_button.png, border=1, width=330)]]
}}}

{{{#!box width=500
==== Manage relations
[[Image(childrelations_manage.png, border=1, width=480)]]
}}}

{{{#!box width=500
==== Child ticket tree
[[Image(childrelations_tree.png, border=1, width=480)]]
}}}

{{{#!box width=500
==== Resolve ticket as {{{duplicate}}} with ticket input
[[Image(childrelations_duplicate.png, border=1, width=480)]]
}}}


== !Bugs/Feature Requests

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

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

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

== Download

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

== Source

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

== Installation

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

== Configuration

When using child tickets it is necessary to create a ticket-custom field {{{relationdata}}}. This field will not be shown on the ticket page but is needed for internal use.
{{{#!ini
[ticket-custom]
relationdata = text
}}}

The rest of the customization may be done with a new admin page {{{Ticket Relations -> Parent Types}}}.

You may also configure them with entries in ''trac.ini''.
Features can be specified separately for each ticket type.

 parent.<type>.allow_child_tickets = True|False:: if child tickets are allowed for this parent ticket type
 parent.<type>.inherit = fieldname 1, fieldname 2, ...:: specify the ticket fields which should be copied to the child
 parent.<type>.restrict_child_type = type 1, type 2, ...:: allow these types ase new child ticket types
 parent.<type>.table_headers = fieldname 1, fieldname 2, ...:: the table headers to be shown for child tickets

In this example the configuration is for tickets of type {{{defect}}}:
{{{#!ini
[relations-child]
parent.defect.allow_child_tickets = True
parent.defect.inherit = description,milestone,summary,project,version
parent.defect.restrict_child_type = defect,enhancement
parent.defect.table_headers = status,project,summary
}}}

== Recent Changes

[[ChangeLog(tracrelationsplugin, 3)]]

== !Author/Contributors

**Author:** [wiki:Cinc-th] [[BR]]
**Maintainer:** [[Maintainer]] [[BR]]
**Contributors:**