Trac: Creation, Plugins, Permissions and more


DatumÄnderung
2012/01/31first version, translation of german version 2
2012/06/29Updated figures (new web interface design)
2012/06/29Added section "issue tracker"

1. Introduction

Trac is a so-called project management tool, which supports you with your projects. For this purpose it offers different modules:

  • wiki
  • timeline
  • roadmap
  • code browser
  • issue tracker

It is freely extensible via plug-ins. On the site Trac-Hacks you can find a list of most of the available plugins. Would you like to have a certain feature in our Trac service, simply open a ticket or mail the support in which you describe the desired feature or, better, the name of a plugin.

2. Create a Trac Instance

Instances of project management tools are always connected to a repository. This means you can have as much Trac instances as you can create repositories. Even those which you can create without a connected repository are linked to a dummy repository in the background. That limits the number of this type to ten yet.

2.1 Creation Without a Repository

The most simple way to create a Trac instance. For doing so, navigate to the Trac section (e.g. via the shortcuts on the left), click the option Create Trac instance without repository, choose a name and click on create tool.

Fig.1: Trac section, creation of a new instance without linked repository.
Fig.1: Trac section, creation of a new instance without linked repository.

2.2 Creation with Connected Repository

To do so you must create a repository of arbitrary type first, which you want to manage with Trac. Soon according Tutorials will tell you how to do so.

Trac instances connected with a repository may be created via two ways: Buttons for this task exist on the repository created successfully page (figure 2) and in the details of a repository (figure 3).

Fig.2: Creation of a trac instance after creation of a repository - here: Subversion.
Fig.2: Creation of a trac instance after creation of a repository - here: Subversion.

Fig.3: Creation of a trac instance via the details of a repository - here: Subversion.
Fig.3: Creation of a trac instance via the details of a repository - here: Subversion.

3. The Details of a Trac Instance

After you created a trac instance, you can always return to the Trac section of our site and click its name to show its details.

Trac is fairly easy to use, so there are only three important settings:

  1. Authorized users: This link carries you to the permission system of your Trac instance. Trac manages its permissions on its own, so this web interface you are currently using is not involved. More information later.
  2. The same applied technically for the plugin section, but we don't let you manage your plugins on your own in Trac's web interface for securities sake. By clicking on to the plugin settings! you can use our plugin management for managing them.
  3. In the lower section you can find information for accessing your Trac instance. Please bear in mind that all services running on this server use the FB4 account and not the HTW account!

Fig.4: The Details of a Trac instance.
Fig.4: The Details of a Trac instance.

4. Selection of Plugins

This section replaces the plugin management contained in Trac. It contains of an information, which Trac instance you are editing and a table of all available plugins. Don't hestitate to try some plugins - they can be deactivated at any time. If the short description doesn't satisfy you, yclick on the hotlink to the official homepage of the plugin on the left column.

Changes of the plugin settings are applied direclty after clicking on apply changes and acknowledged by a confirmation message on the top of the page.

Fig.5: The available plugins of a Trac instance.
Fig.5: The available plugins of a Trac instance.

5. Permissions

The permission system is based subjects which are similar to roles like those in the SQL standard. They do not differenciate between users and groups. A simple example: Does a subject named hans has the WIKI_ADMIN permission, a user logged in as hans as well other users who are member of this subject (in the manner of group) are administrators of the wiki.

In Trac, there are two special subjects: anonymous is applied to not logged in users automatically. Logged in users get a subject named after their login name (e.g. s0123456) and authenticated.

In a standard installation some permissions are granted to those two subjects: Anonymous users could read all, authenticated users can edit nearly everything. Those permissions are a security risk in our environment, because the login is done via the whole user directory of the FB4 - everyone with a FB4 account can login!

However, the most projects are non public and not every student should be able to edit everything. Therefore, those default permissions has been removed, so that every student may login, but doesn't have any permissions, which is most likely not to login. This is the reason why in comparison to a default Trac installation there are no entries for this role in the permission table.

Instead of that the two subjects (groups) developer and priviledged exist, which base on experience. First is for normal developers who should see all and should be able to use the issue tracker and the wiki. In a big project in which the whole class is involved, this is the best group for most students. The latter group has all rights except of TRAC_ADMIN, so that no permissions can be managed. So a priviledged student can't ace the creator of the Trac instance out. This group is adequate for student project managers if the tutor doesn't want to share its TRAC_ADMIN rights with them.

Example

In figure 6 you can see the permission table directly after creation of an instance. You can see the given subjects developer and priviledged, as well as the TRAC_ADMIN permission for the owner. Do never delete this, because only an admin is able to help you out of this!

Fig.6: Permissions after creation of a Trac instance
Fig.6: Permissions after creation of a Trac instance

Let's assume there is a kind student s0123456 who wants to participate in the project. We use the field Add Subject to Group, add his login name as subject and developer as group (figure 7).

Fig.7: Assignment of a subject to a group.
Fig.7: Assignment of a subject to a group.

This student has now get the order to maintain milestones. We'll grant him every permission that's concerned with them via entering his login name as subject and the appropriate permission in the field Grant Permission (figure 8).

Fig.8: Assignment of a permission to a subject.
Fig.8: Assignment of a permission to a subject.

We want to inform the world about our superior project. So we grant anonymous the permission to view the wiki (figure 9).

Fig.9: Assignment of the WIKI_VIEW permission to anonymous users.
Fig.9: Assignment of the WIKI_VIEW permission to anonymous users.

After this action the permission table should look like figure 10.

Fig.10: New permission table after changes.
Fig.10: New permission table after changes.

Last but not least: Trac unfortunately doesn't use the term subject all the time and uses user and group depending on the context, this is a full-blown-up permission system like you know from SQL! Permissions can be inherited over subjects, so an alternative way to achieve our standard permissions shown in figure 11 would be that priviledged inherits all permissions from developer and gets only its additional permissions explicitly.

Fig.11: Alternative implementation of default permissions
Fig.11: Alternative implementation of default permissions

6. Usage

This is a short introduction into the usage of trac. It's not meant for substitution of the comprehensive help and tutorials on the internet, but should give beginners an idea about using this service.

6.1 Wiki

Fig.12: The integrated Wiki
Fig.12: The integrated Wiki

Trac comes with a full blown up Wiki, which is important especially for big projects. After the creation of the instance the wiki contains a full copy of Trac's own Wiki of the currently installed version which you can access every time.

Please understand that changes we have done to our server could lead to differences between the Trac Wiki and the real situation on the server. If you find such an entry, we would be lucky if you would mail us informing about this glitch.

6.2 Timeline

Fig.13: The timeline of your project
Fig.13: The timeline of your project

The timeline shows changes done to the wiki, tickets, milestones, and, if available, the repository.

6.3 Roadmap

Fig.14: Milestone overview
Fig.14: Milestone overview

Milestones are certain goals during the project. If tickets are assigned to this milestone, a progress bar showing the quotient between open and closed tickets appears and shortcuts to open, closed and all open tickets are shown.

6.4 Source Code Browser

Fig.15: Browsing the repository
Fig.15: Browsing the repository

If your Trac instance is connected to a repository, you may browse it here similar to the web view of the repository software. However, the code browser of trac offers more features: The size, revision number, age and commit message of the current state of a file or folder is shown. In addition, single files or the whole repository can be viewed in the state of a certain revision (controls on the upper part), changesets (click on rev.) can be shown and the difference of a file between two versions can be analyzed (click on file).

6.5 Issue Tracker

This is probably the most important part of Trac. Tickets are digital pendants to the well known ToDo-Lists. On them, the name of a single task, its description, its submitter, its owner and much more is described. You can nearly add any field by using plugins. Most fields are described in the admin panel section, since their available options are set there.

There is no right or wrong way to use a ticket system. You can use them just as notepads or as a complicated enterprise ticket system - everything is possible. That's why the ticket workflow is not further described, since you will find your own way of dealing with tickets by using them some time.

So-called reports that are located in the View Tickets menu bar are the last important thing to know about tickets. They are not just displayed in a list, but in a table that is backed up by a real database query. Active Tickets, for example, lists all tickets that status is not closed. In general, the provided queries should meet the requirements, but new reports can be added at any time. An interesting addition to the WHERE clause of a report would be:

WHERE owner == 's0123456'

, where your own matriculation number is substituted. This query would show only the tickets of this user.

Fig.16: Project wide search
Fig.16: Project wide search

This is the most self explaining section: It enables you to search all tickets, changesets, milestones and the wiki.

6.7 Admin-Panel

Fig.17: The control center of your Trac instance
Fig.17: The control center of your Trac instance

Here you can change all settings you are permitted to change (except plugins), so you don't need access to the command line on the server for using trac-admin commands, which is often mentioned on the internet.

Der Bereich teilt sich in zwei Bereiche auf: General und Ticket System. Alle Punkte des letzteren Bereiches lassen euch mögliche Werte für gleichnamige Eigenschaften bei Tickets erstellen. Falls ihr den ein oder anderen nicht benötigt, könnt ihr bei all diesen Punkten die entsprechende Funktion deaktivieren, indem ihr alle Werte der Eigenschaft entfernt.

6.7.1 Basic Settings

Hier könnt Ihr eurem Projekt einen anderen Namen geben (die URL ändert sich dabei nicht), ihm eine ausführliche Beschreibung verpassen und eine URL angeben. Da das Trac-Icon links oben immer auf die Studi-Seite verlinkt und die Zusammenfassung aller Projekte durch Trac im Moment deaktiviert ist, sind diese Einstellungen im Moment eher nutzlos.

6.7.2 Permissions

See Permissions above.

6.7.3 Components

Fig.18: Components in the admin
Fig.18: Components in the admin

You can assign tickets to components of your project. Those may be backend, frontend and android app, as well as some abstract issues like documentation. It's your choice.

6.7.4 Milestones

Fig.19: Milestones in the admin
Fig.19: Milestones in the admin

This is the place where the data of Milestones are edited. You can choose name, descrition and due date. An example is the important end of a project!

6.7.5 Priorities

Fig.20: Priorities in the admin
Fig.20: Priorities in the admin

high is the lowest priority, right?

6.7.6 Resolutions

Fig.21: Resolutions in the admin
Fig.21: Resolutions in the admin

How has the ticket been closed? Fixed? Bug not found? Duplicate? You may add a done for simple tasks.

6.7.7 Severities

Fig.22: Severities in the admin
Fig.22: Severities in the admin

This is an option which is barely used because the priority already makes a good separation of tickets. Small advice: What you enter - like in all ticket settings - is arbitrary. This may also be hard, easy, S, M or L or mandatory and optional...

6.7.8 Ticket Types

Fig.23: Ticket types in the admin
Fig.23: Ticket types in the admin

defect (bug), enhancement (new feature) und task should be self-explaining.

6.7.9 Versions

Fig.24: Versions in the admin
Fig.24: Versions in the admin

Last but not least you can assign tickets to versions. Is a feature too hard for Version 0.2? No problem, just change to version 0.2!