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

= Manage multiple user projects with one Trac instance 

== Description

This plugin lets you easily '''manage multiple user projects with one Trac instance''' or, respectively, one Trac database (.db file).

This is not a meta project in front of several other Trac projects. It implements the idea of [T:wiki:TracMultipleProjects/SingleEnvironment].

Key features:
 * Milestones and versions are assigned to their projects, and both are displayed on the roadmap. There are several possibilities to filter by projects on that page, and also the timeline.
 * Components can be assigned to all or only certain projects.
 * 'New Ticket' will just offer the associated milestones, versions and components of the chosen project. This requires a new custom-ticket field 'project'.
 * You can rectrict access to certain milestones, versions and tickets by defining members or non-members of a project.

This is already running stable in a real production environment.

'''Note''': The Multiple Project feature in the sense of having a meta Trac project on top of several Trac projects is discussed in T:#11025 (formerly T:#130) and the unscheduled milestone [T:milestone:topic-multiproject Trac topic-multiproject].

=== Plan

In testing state:

[[TicketQuery(component=SimpleMultiProjectPlugin&keywords=~testing)]]

Work in progress:

[[TicketQuery(component=SimpleMultiProjectPlugin&keywords!=~testing&status=assigned|accepted)]]

Still just an idea:

[[TicketQuery(component=SimpleMultiProjectPlugin&keywords$=planned&status!=assigned|reopened|closed)]]

=== Technical thoughts

This plugin adds a new resource 'project' implemented by database table:
 1. smp_project: a list of all defined projects[[BR]]
 Actually, most database tables of Trac core related to resources would need a new column 'project_id'. This way tickets, components, milestones, versions or even wikis could attach to certain projects. Since a plugin just adds stuff but cannot change the core structure, it implements the new dimension 'project' not by adding a new column to each resource table but rather by adding several mapping tables smp_[resource]_project, each one mapping a certain resource to projects:
 1. smp_milestone_project: the association of milestones to projects
 1. smp_version_project:   the association of versions to projects
 1. smp_component_project: the association of components to projects

=== Example

All actions are also possible with the ''trac-admin'' script. See ''trac-admin <your-trac-env> project help'' for the list of available commands.

Admin Interface:
[[BR]]

[[Image(admin_project.png, 400px)]]

----

Add project summary and description. This is displayed on the roadmap page then:
[[BR]]

[[Image(admin_projects_modify.png, 400px)]]

----

Associate a milestone with a project:

 * Mapping milestones and versions to a project is supported
   * via main menu item "Admin" -> "Ticket System" -> "Milestones" / "Versions". 
   * Another way is doing it from the ''Roadmap'' page:
     1. From the ''Roadmap'' Page, find the desired milestone/version and click it.
     2. Scroll to bottom of page and "Edit" the page. Select the project from the given combobox.
   * via ''trac-admin project'' script.
 * Note: "New Ticket" with a chosen project only offers milestones and versions mapped to that certain project.

[[Image(edit_milestone.png, 400px)]]

----

Group milestones and versions on the roadmap by project, show project summary and description in the header of the project box, and display only projects chosen in the filter box:
[[BR]]

[[Image(roadmap_projects_filter.png, 400px)]]

----

Display only tickets in the timeline of projects chosen in the filter box (adapted from TimelineComponentFilterPlugin):
[[BR]]

[[Image(timeline_projects_filter.png, 400px)]]

----
You also can include the Project Name in your Ticket Queries by adding a join to "ticket_custom".
Example:

{{{#!sql
SELECT p.value AS __color__,
   id AS ticket, summary, 
   tc.value AS 'Project-Name', # display the Project Name in the Ticket Overview
   version, milestone, t.type AS type,
   owner, status,
   time AS created,
   changetime AS _changetime, description AS _description,
   reporter AS _reporter
  FROM ticket t
  LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
  LEFT JOIN ticket_custom tc ON t.id = tc.ticket AND tc.name = 'project' # add the join to ticket_custom and only select the Project-Name
  WHERE status <> 'closed'
  ORDER BY CAST(p.value AS integer), milestone, t.type, time
}}}

== Bugs/Feature Requests

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

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

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

== Download

Download the zipped source from [download:simplemultiprojectplugin here].

== Source

You can check out SimpleMultiProjectPlugin from [http://trac-hacks.org/svn/simplemultiprojectplugin here] using Subversion, or [source:simplemultiprojectplugin browse the source] with Trac.

== Installation

 1. Add a custom ticket field 'project' in your `trac.ini` file to give tickets the information to which project they belong. Milestones selection depends on that as well:
 {{{#!ini
[ticket-custom]
project = select
project.label = Project
project.value =
}}}
 1. Generate the plugin .egg file from sources:
 {{{#!sh
python setup.py bdist_egg
}}}
 1. Copy the plugin to the plugins directory of your Trac installation:
 {{{#!sh
cp dist/SimpleMultiProject-0.0.1-py2.6.egg /instance_trac/plugins/
}}}
 1. Restart Apache: after installation of this plugin Trac needs a database upgrade:
 {{{#!sh
trac-admin /instance_trac/ upgrade
}}}
 1. Give permissions to certain users. Available permissions are:
   - {{{ PROJECT_SETTINGS_VIEW }}} - you can see the list of projects with their description and their component mapping on the Admin panel
   - {{{ PROJECT_ADMIN }}} - full access, you can also create and delete projects, and map to milestones, versions and components
 1. Since plugin version 0.4 we support project-wise restriction of resources to a subset of users (#11367). Switch on the plugin component ''ProjectTicketsPolicy'' to activate it, and add the following to your `trac.ini` file:
 {{{#!ini
[trac]
permission_policies = ProjectTicketsPolicy, ... any other ...
}}}
 Define a comma-separated list of users or groups in 'Admin' -> 'Manage Projects' -> 'Projects' -> '<project name>' -> 'Restrict to users' to limit the access to certain projects, such as milestones, versions and tickets. For example, set
    - {{{ john, mary, group1, authenticated }}} to restrict to this set of users
    - {{{ !, bob, anonymous, group2 }}} to exclude from the project.

== Recent Changes

[[ChangeLog(simplemultiprojectplugin, 5)]]

== Author/Contributors

'''Author:''' [wiki:crossroad], [wiki:falkb], [wiki:thomasd], [wiki:Cinc-th] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''