Developing Programmers .com

This tutorial aims to teach you how to use the CVSTrac and Trac tools. I assume an administrator has already set one or both of them up for you and that you just need to get comfortable with the tools themselves. The tutorial should also be useful for people trying to decide whether to use one of these systems, but I do not cover how to set them up or administrate them. Let me know if you’d like a future tutorial covering CVSTrac / Trac setup and administration.

CVSTrac and Trac are web extensions for CVS and Subversion respectively. If you are unfamiliar with CVS and Subversion and what they have to offer, I suggest you look back over the last two articles in this thread: “What Is Configuration Management?” and the “CVS and Subversion Combined Tutorial.” CVSTrac and Trac extend on these two tools by adding a web interface that lets you:

• Browse the files in the repository, at any revision.
• Use a “Wiki” to collaboratively write documentation with the other authors.
• View a timeline of changes; both for historical reasons and just to keep up to date with what everyone is doing on a project.
• Add and view “tickets”, which are like “to-do” items describing bugs, enhancements or anything else on the project that requires work.
• Search the Wiki, commit comments and tickets.

Note that checking in and committing code are not in this list. Neither CVSTrac nor Trac are user interfaces for CVS/Subversion. They are designed to go along side CVS/Subversion to extend what is offered, not to be a simple UI for them. With both systems you continue to use CVS and Subversion as normal.

CVSTrac and Trac are very similar tools. The main difference is that CVSTrac is made especially for CVS and Trac is made especially for Subversion. There are other differences in security and administration features too but I won’t cover that in a tutorial aimed at users.

If you are trying to decide which tool to use, I suggest that the choice of CVS or Subversion is far more important and your choice of “Trac” tool should follow from there; although knowing what tools are available for each is probably a good thing.

Users

Both CVSTrac and Trac are sensitive to which user is operating them. An administrator can set up permissions for each user, and once you log in certain options from the full set might be removed from the menu if you do not have the right permissions to use them. This is handy if you want a client (or the public) to be able to view parts of your tracking site but not to be able to change anything.

In a commercial setting you will usually have to log in before you can do much with either system. In an open source setting they may be open for the public to make changes.

The Options

CVSTrac and Trac both use a top menu to list the main page / mode options. CVSTrac adds options specific to the mode it’s in to the same menu. Trac adds a small sub-menu under the main one for mode-specific options.

Home Page

CVSTrac has a “Home” page, listing the modes available. Trac doesn’t have a built in Home page; instead it defaults to the index for the Wiki system, which basically amounts to having a fully customizable Home page.

Home screens for CVSTrac and Trac.

Wiki Page

According to Wikipedia, “a wiki is a type of website that allows users to add and edit content and is especially suited for collaborative authoring.”

The Wiki page is really a whole collection of pages, each of which can be edited by simply clicking the “Edit” button and changing the text in the form.

View of CVSTrac Wiki page and editing a Trac Wiki page.

The Wiki text has a markup format that is similar to other Wiki systems, but both CVSTrac and Trac have their own unique quirks. Luckily, they also both come with pre-built Wiki pages explaining their own formatting tricks: CVSTrac Formatting and Trac Formatting.

Some general principles seem to be common to nearly all Wikis including these:

• Blank lines indicate a new paragraph.
• Mixed case combined words like “CatFood” or “NewFeatures” or “MeetingMinutes” are considered to be hyperlinks. If the page doesn’t exist yet, type the link name anyway to create the page.
• Adding a page is as simple as following a link to a page that isn’t defined yet and hitting the “Edit” button.
• External links can be added by just typing the full URL. If it looks URL-ish then the Wiki system will make a link out of it.
• Add bullet points by writing *: (for CVSTrac) or * (for Trac) in front of each point, similar to writing bullet points in emails.

The general goal of wiki markup is to provide a basic set of document markup features in a way that doesn’t distract you from the business of writing the most important part: the text itself.

A Wiki is a surprisingly handy tool to have available for a project. We use it to discuss and document data structures, overall design, major decisions, and as a place to write up meeting minutes. We also use the “attachment” feature a lot to post images and diagrams of our designs. If you include a link to an image in a Wiki, it automagically puts the image in-line into your Wiki page.

Here’s an example:

= Simple Heading =

A paragraph containing a WikiLink
and an http://external.link.html

 * A bullet point
 * Another bullet point
 * A third point

An inline image:

http://mydomain/image.jpg

Browse Source

It’s handy to be able to view changes online; I use this feature to explain bits of code to my boss who hasn’t checked out a copy of the project, and also to view what’s going on in parts of the program that others are working on. CVSTrac and Trac both let you view what’s in the repository, and even to turn back time and see previous versions of your code.

CVSTrac and Trac Repository File Browsers.

In both systems you can simply click on directories to view inside them, or click on filenames to view the contents of files.

Note that CVSTrac optionally shows deleted files. This is because CVS stores each file’s history independently so it’s harder to say “at this revision that file wasn’t there” without relying on time and date stamps which may or may not be accurate.

Subversion has a stronger concept of a revision, where a revision is the state of your entire repository at a given commit. This lets it show you only the files that existed at the revision you have chosen.

Each file has links you can follow that list previous commits so you can view older versions of the file, or a summary of changes and commit notes.

Commit Notes

An important feature of both CVSTrac and Trac which requires no extra effort if you’re already using CVS / Subversion is that it will display commit notes for any given commit. Subversion numbers commits and Trac uses the same numbering. CVS doesn’t natively number commits but CVSTrac sets up its own numbering system.

Commit notes in CVSTrac and Trac.

In the screenshots above, the CVSTrac example has better comments, indicating which ticket is fixed by the commit. The screen grabs show that Trac has prettier “diff” output when it shows at the bottom of the page what changed in this commit.

Add Tickets

CVSTrac and Trac both offer a “ticket” database to keep track of bugs, feature requests, and anything else you might need to do to work in a project.

Tickets are inherently tied to commits. A ticket says what you need to do and a commit says what you’ve done.

Generally the process goes like this:

• You realise something needs to be done (eg. through testing).
• You write a ticket describing what needs to be done.
• You assign a priority to the ticket and decide who should do it.
• That person checks out the relevent code.
• The developer and testers add notes to the ticket while they’re working on it
• The developer fixes the problem in their working copy of the code.
• The developer commits their changes, making sure the commit comment mentions which ticket number they are fixing.
  • If they use the notation #n where n is the ticket number then CVSTrac and Trac will both make a hyperlink from the comment to the ticket for you.
  • If they use Wiki formatting in the commit comment, it will be honoured by both CVSTrac and Trac when displaying information about that commit.
• The ticket is marked as “Fixed” and closing comments are added to the ticket.
  • If the ticket comments contain the notation [n], where n is a commit number, then CVSTrac or Trac will create a hyperlink for you from the ticket to the commit detalis.
  • As usual, Wiki notation will be honoured here.

A ticket can be bounced around between different developers and testers by changing its “owner” attribute.

Viewing a recently fixed tickets should ideally tell you who did what to fix it, with links to the actual commit notes.

Adding a new ticket in CVSTrac and Trac.

Tickets have a number of fields including:

• A short and long description and notes, for listing and discussing what the problem is.
• Attachments for any screen shots etc that help describe the problem.
• Severity and priority. The difference between severity and priority is how serious the problem is versus how important is it to fix the problem immediately. A crash bug in a rarely used feature might be severe but low priority.
• System version and component to narrow down where the problem is.
• Owner is the nickname or email of a developer who is currently responsible for fixing this ticket. Each developer can ask CVSTrac / Trac to display just their tickets. Depending on how the process works at your workplace, you might need to pass responsibility on to other developers or testers after you have had a look at it.

Ticket Reports

In general, reports are how you view the tickets that you have created.

A “report” in both CVSTrac and Trac is simply a view of the data it has stored. Most reports show different views of a project’s tickets but there is some flexibility to include other data as well.

The Reports page in CVSTrac and Trac.

The Reports page shows a set of pre-defined reports. This will include things like “all active tickets”, “just my tickets”, etc. Simply click on a report and you will be shown a table of all the tickets that match the report query.

Matches for a report query in CVSTrac and Trac.

Reports are simply souped up SQL queries, so if you know a little SQL or are comfortable with modifying examples then you can modify existing reports and create your own new ones. Both systems let you create a new report by copying an existing report to use as a template.

Each report has a number, and in Trac (but not CVSTrac) the notation {n} (where “n” is the report number) will link to a report from any wiki, commit note, ticket note or search.

Roadmaps

Both CVSTrac and Trac have “milestones”, which are markers saying when you have acheived some overall goal like “version 2 release”.

Roadmaps are specific to Trac and let you view and manage future milestones that you are aiming towards. They offer a summary of where the project is going. Each ticket you add can be associated with any given milestone.

The Roadmap page in Trac shows your future (and optionally your past) milestones, notes about each, and a progress bar indicating how many of the tickets for that milestone have been acomplished.

Roadmap View (Trac only)

Timeline

The timeline is an important and popular view in both CVSTrac and Trac. It shows a list of everything that has changed within the date range you give it. The date range defaults to “recent changes”.

The timeline view lets you see what you have accumplished, how the project has changed, and what others have changed that you might want to keep up to date with.

Each morning that I work on a shared project I check the timeline view to see what my workmates have changed during the previous day. If I have any concerns I speak to them or write a ticket about it. If they come to me with a question then I already know what they’ve been working on lately. And if I need to use or modify their code I know what’s going on.

The timeline can show:

• Any date range you set
• Commits
• New tickets
• Changed or completed tickets
• Wiki page changes (it’s usually worth reading other people’s wiki changes!)

CVSTrac and Trac Timeline Views.

In short, the timeline keeps you in sync with the others in your project.

Search

Both CVSTrac and Trac have Search pages which let you find any ticket, commit, or Wiki page in your system.

These work as generic search engines do: type a few words that you know will be in the document you’re looking for, and let it rip.

There are checkboxes to limit the search to one kind of data (tickets, commits or Wiki).

A feature that isn’t as well known as it should be is that you can type any “link notation” into a search box and be taken straight to the page you linked to.

Search Pages in CVSTrac and Trac.

Trac also has a “mini search” at top of every page, to keep it available.

Trac’s mini search

A Note About Link Notation

I’ve mentioned link notation a few times and will summarize the different sorts of link here.

• Wiki links: Use mixed case names like WikiLink or see CVSTrac/Trac wiki formatting documentation for other linking methods.
• Ticket links: A hash sign followed by the ticket number. For example, #23 links to ticket number 23.
• Commit links: The commit number enclosed in square brackets. For example, [23] links to commit number 23. Note that Trac also uses square brackets for its generic link-to-anything notatoin (eg [wiki: not_mixed_case]). See the Trac Wiki format documentation for details.
• Report links: In Trac only, the report number enclosed in curly brackets. For example, {23} links to report number 23. Note that CVSTrac uses curley brackets as its generic link-to-anything notation (eg {rptview:23}). See the CVSTrac Wiki format documentation for details.

This notation is self consistent throughout CVSTrac or Trac and can be used inside commit notes, tickets, wiki pages and of course in searches to take you directly where you want to go.

Wrap-up

This tutorial extends on my previous CVS / Subversion tutorial, detailing popular web tools that are used to extend them.

I have covered the basic elements of CVSTrac / Trac, outlining what they have to offer:

• Commit note viewing.
• Repository File browsing.
• Wiki for collaborative documentation.
• Ticket database with various report views.
• Timeline view to keep you up to date with changes.
• Search engines to find tickets / commits / wiki pages.
• A self consistent notation to link commits, tickets and wiki pages.

This article was the third related article in this thread. The others are:

• What Is Configuration Management?.
• CVS and Subversion Combined Tutorial.

Let me know what further articles you’d like to see in this thread or others.

Have fun!