[[TOC]]

= Project administrators Page =

This page aims at giving a spectrum of all the features we propose to developers in CP3, as well as help on using these features. 

== Users management ==

Users are managed through the accountmanager plugin. This allows you to add/remove users and change passwords. Users can also register through the register link after solving a repatcha. If you want to get notified on user registration, do not forget to configure the accounts:notifications section of the admin page.

Permissions are dealt form the general:permissions section. we advise you to define groups in order to define permissions globally.

== Wiki ==

=== Features ===

The Trac wiki offers features linked to other components of Trac: issue tracking and code browsing. This means that you can make very simple TracLinks to tickets, ticket comments, source files, changelogs, etc... You can also perform queries in the ticket database (see [#Queries here]). 

Wiki syntax is inspired by [http://moinmo.in/ moinmoin]. This means that you already have a [http://moinmo.in/ moinmoin] or [http://twiki.org/ twiki] we have means to import it. Some corrections will have to be done by hand, but most of your content will be preserved.

Another interesting feature of the Trac wiki is InterTrac. This allows to make links to other Trac projects (even external ones) as directly as you would do it for your own project. This feature has to be activated by the administrators (fill a [/newticket New Ticket] on this site). 

=== Permissions ===

Permissions on the wiki pages are managed through a file you can edit through the [/admin admin] panel. You can define all types of permissions (read, create, edit, delete) for individual pages or recursively. For instance, the following configuration:
{{{
[groups]
admins = usera, userb, userc

[wiki:WikiStart@*]
@admins = WIKI_ADMIN
authenticated = WIKI_VIEW
* = ""

[wiki:TestPage*@*]
@lesadmins = WIKI_ADMIN
* = ""
}}}

Gives administration rights on the frontpage to all users in the '''admins''' group, allows authenticated users to see it but anonymous users are redirected to the login page. Administrators can see and manage the testpage but no one else can see it. This overrides the general Trac wiki permissions.

=== Important note about permissions ===

There are two or three sets of permissions on any trac project hosted here. the first is the global trac permissions system available through the Admin tab, general section, permissions subsection. This is where you basically decide who the administrators of the site are and what are the default permissions for authenticated and anonymous users.

The second permissions set is in the account section, under page permissions. This is where you set wiki permissions to override the default ones in the general permissions section. You have to check consistency of usernames here. Groups are independant of trac groups and you should then define new groups here.

Finally, you will find the svn repository permissions under svn -> permissions. Once again, this is an independant file and groups have to be redefined. 

This setup allows great flexibility at the cost of sometimes redundant groups. There is unfortunately now way to define groups globally. 

== Source code repositories ==

The Trac software includes a repository browsing part. This allows to browse the files of your source code (versioned repository), see changes between versions (revisions), look back in time on a file, ... It can be accessed through the ''Browse source'' top menu link (''/projects/xxx/browser'', where xxx is your project name). Permissions are set via the ''Admin'' page -> left menu ''General'' -> ''Permissions''; this is the ''BROWSER_VIEW'' action.

As this feature does not help you to download/work on your repository in production, the IT team proposes to host your repository. It will then be made accessible through the https+webdav protocol with the same users and passwords as for the Trac website, although the permissions are different and not inherited from Trac (permissions shown above).

The project repository is located at ''/sources/xxx/''. This is where you will checkout, branch, commit, merge ... your code.

=== Repository permissions ===

[http://subversion.tigris.org/ Subversion] is the Source Code Management tool we recommend for your project. 

Other source code management tool like git, bazaar and mercurial are also supported. Browsing in Trac works perfectly fine with those, although they are not in a stable state yet. However, access permissions are impossible to handle with these latter tools. This means all authenticated users have read (checkout, branch) and write (commit, merge) access to your repository. 

For SVN on the other hand, all kinds of permissions schemes are possible. For instance:

||                  || '''Read Trunk''' || '''Write in Trunk''' || '''Read Branches''' || '''Write in Branches''' ||
|| '''group A (admins)''' ||Yes||Yes||Yes||Yes||
|| '''group B (devels)''' ||Yes||No ||Yes||Yes||
|| '''group C (others)''' ||Yes||No ||No ||No ||

This simple scheme allows developers to create and manage their own feature branches while preventing them to harm the trunk. Administrators can then commit/merge tested branches to the trunk. All other users (anonymous or not) can read the trunk to get the latest version for testing purposes.

Permissions for the SVN repository can be reviewed via Trac: ''Admin'' page -> left menu ''Subversion'' -> ''Permissions''

One can still use the power of bazaar's "local versioning" through the [http://wiki.bazaar.canonical.com/BzrForeignBranches/Subversion bazaar-svn] plugin of bazaar.    

If you are a beginner (or not):
  * [http://svnbook.red-bean.com/en/1.5/index.html Subversion tutorial]
  * [http://doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches.html Bazaar Tutorial]


Contact the IT team for planning a first draft of the workflow, of the source code tree and a global scheme for the permissions.
== Tracking system ==

=== Tickets ===

Defects and feature requests are handled in Trac through TracTickets. The adminstrators can determine who has what kind of [TracPermissions permissions] on tickets. By default in CP3, authenticated users can create and comment tickets, as well as edit the most basic fields.

Tickets can be linked to Milestones and to software versions. '''Milestones''' allow you to fix a deadline for a set of features or bugfixes. The '''roadmap''' tab of your project tells you how your milestones progress and when they are due. 

Default ticket fields are :
  * Summary and description
  * Reporter
  * Type: dropdown menu for the type of ticket (bug, request, enhancement/suggestion, ...). You can set the types via the admin page.
  * Component: you can divide your project in components
  * Priority
  * Cc-list: list of people that will get e-mail updates
  * I have files to attach

All dropdown lists are editable through the Admin tab. 

=== Queries ===

Most of the ticket fields can be used later to make [TracQuery queries], for instance: 
{{{
[[TicketQuery(priority=major,order=time,desc=1,max=5,format=table,col=resolution|summary|owner|status|time)]]
}}}
Will show:
[[TicketQuery(priority=major,order=time,desc=1,max=5,format=table,col=resolution|summary|owner|status|time)]]

Instead of the "table" format, you can use "list", "compact" or event "count" for results like:

There are [[TicketQuery(priority=major,format=count,component!=todo)]] major priority tickets at the moment. Among them, [[TicketQuery(priority=major,format=count,status!=closed,component!=todo)]] are still open. Here is the complete list (time-ordered):

[[TicketQuery(priority=major,format=list,component!=todo,order=time,desc=1)]]

== Plugins ==

The Trac software is complemented by a set of plugins. Some of them are integrated into Trac by default, while others are available for installation. We recommend that you don't install and manage plugins by yourself. A simple request to the IT team (fill a ticket here) is better, as we will install the plugin for all projects at once.

A lot of plugins are already installed, although not all activated for this project:

  * '''!AutocompleteUsers''' for the reporter, assign, cc-list fields
  * '''Authz-policy''' and '''!AuthzPolicyEditor''' to manage the permissions on wiki pages
  * '''!AccountManager''' to allow administrators to manage their users form the web interface, allow users to register, etc...
  * '''!PermRedirect''' to redirect users trying to access forbidden pages to the login page
  * '''!TicketGuidelines''' to provide advice at the creation and edition of a ticket
  * '''!TracMath''' to allow latex code in the wiki
  * '''SVNAuthz''' to manage permissions on svn repositories from the admin page
  * '''!TocMacro''' to generate tables of content at will
  * '''!TicketStats''' to show a plot of open and closed tickets
  * '''sensitivetickets''' to allow confidential tickets
  * '''!MasterTickets''' to provide a worflow based on tickets blocking other tickets ([http://trac-hacks.org/wiki/MasterTicketsPlugin example])

And many others ! The full list is available on the [http://trac-hacks.org Trac-Hacks] website.