So you want to build a software team? Part 5: Trac Wiki and Source Browser

In the last installment we set up Trac, and I hinted at a couple of its features. But what should we actually be using it for?



Well, let's take a look inside.



When you first visit Trac, you're presented with a standard intro page that tells you about Trac. It's useful to start, but it's not the key information we're going to want every time we visit the Wiki. As such, I tend to either shift it to another page, or just add new content above it.



This new content should help developers to work with the new systems you've just set up, so useful content to add includes:




  • A summary of tools available on the server (with versions)

  • How to connect to the dev server via ssh and samba

  • Where the central repository is located

  • Where each developer's sandbox is located

  • How to create and access databases

  • Who your local experts are

  • Links to library software manuals, the MySQL and PHP manuals etc

  • Info such as network setup, mailserver names, all that sort of minutiae



As users may be quite new to these tools, it's usually worth adding a couple of quick reference guides to things like the unix command line or svn commands - either links or you own summaries. Just pasting in the output of svn help is pretty useful.



Beyond this (and while we've not covered these topics yet) it's useful to have notes on:




  • Your server's backup schedule and policy

  • The coding standards you're applying



OK, so much for the wiki functionality. What else is in here? The nav bar at the top of the page gives us a list of Wiki, Timeline, Roadmap, Browse Source, View Tickets, New Ticket and Search.



Wiki we've seen. Timeline we briefly mentioned last time as a summary of changes made to the code and wiki; it tends to be worth a glance occasionally to sanity check changes and commit frequency and messages. Search is useful too; it lets you hunt for info within all areas of the wiki - and if your documentation is searchable, people use it more and add to it. See below for a way to extend this search and add it to a user's browser for even greater ease of use.



Let's take a look at one more option for now. Browse Source is a link to an SVN repository browser. As is generally the way in Trac, it's fairly lightweight and fairly easy to use. It uses repository connection data that's supplied when you initialise your trac project, and gives you an easy way to browse the repository contents, finding out what's where, who changed it, when, and how. You can do all of this with the SVN command line tools, but it's far easier in here, and a repository browser is invaluable for getting the full historical power of version control.



The browser also has the useful feature that, being part of Trac, it integrates smoothly into the wiki and ticketing systems. By typing r1234 (or any SVN revision number) in a wiki page, you'll get an automatic link to that changeset in the repository browser. You can also link to related files using Trac's source: syntax - check out the TracLinks page in your copy of Trac for more info. Also, any wiki links you add to your subversion commit messages will be linked in the Timeline and Changelogs within Trac.



Next time, we'll take a look at task allocation within a project, with the help of the ticketing system within Trac.



Before we do that though, here's how to add Trac search directly into your Firefox or IE7 browser. It's not the most elegant solution, but it works.



First, we need to create and host an Open Search specification document that can act as a plugin for both Firefox and IE. We'll host this file in the root folder of the webserver which we've set up to host subversion and trac, which in our example is /var/www/html for devbox.example.com



Copy the following into /var/www/html/trac-search.xml:




<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Devbox Trac Search</ShortName>
<Description>Search Devbox Trac</Description>
<Contact>webmaster@devbox.example.com</Contact>
<Image height="16" width="16"
type="image/x-icon">http://devbox.example.com/trac/uberproject/chrome/common/trac.ico</Image>
<Url type="text/html"
template=
"http://devbox.example.com/trac/uberproject/search?q={searchTerms}&amp;noquickjump=1&amp;wiki=on" />
</OpenSearchDescription>


Obviously, adjust hostnames, paths and descriptions to your own system. Note that the URL constructed here only searches the wiki - I find that's usually what I want to do anyway.



Next, locate the template files for your Trac project. In our example, they'll be at /opt/trac/uberproject/templates. We want to edit the header template site_header.cs. This file starts off pretty empty, and we'll add the link to the search plugin, plus some standard javascript that seems to be required to install a search engine. The resulting file looks like this:




<?cs
####################################################################
# Site header - Contents are automatically inserted above Trac HTML
?>
<link rel="search" type="application/opensearchdescription+xml"
title="Devbox Trac search" href="/trac-search.xml">
<script type="text/javascript">
/**
* Install a search engine (opensearch)
* Returns false in case of success (sic!) because that will keep the file link
* from being followed.
*/
function addEngine(engineURL) {
if (window.external && ("AddSearchProvider" in window.external)) {
window.external.AddSearchProvider(engineURL);
return false;
} else {
alert(error_opensearch_unsupported);
return true;
}
}
</script>
<div style="position: absolute; right: 20px; color: #bbb; cursor: pointer">
<a onclick="addEngine('http://devbox.example.com/trac-search.xml');">Install trac search plugin for IE7
& Firefox</a>
</div>


And that's it. Each page of your trac project should now contain an install link for the plugin, which will appear in your search box with the trac 'paw' icon.

Posted by parsingphase, 2008-08-12 21:37

Anonymous user

Login

Blog

Contact

I'm currently available for contract work in London as a Senior PHP Developer. Contact me for a CV, rates, or a chat.

Twitter @parsingphase
Email richard@phase.org
Github parsingphase
LinkedIn Richard George
Flickr parsingphase