Teamware

Introduction

• No programmer is an island
  • You may be the only person writing code today, but you:
    • Probably depend on tools and libraries written by other people
    • May have inherited the project from someone else
    • Ought to be thinking about who's going to take over once you're gone
• As open source spreads, being able to work in teams becomes even more important
• This lecture looks at some of the things teams have to do to stay productive
  • All of which will make you more productive as an individual, too
• Introduce the ideas by showing you how to use a web-based project coordination tool called Trac
  • Open source
  • Reliable
  • Easy to set up and install
  • Modular, so that you can add new features (relatively) easily)
• Comment on this slide

Overview

• Trac is a Python CGI program that provides:
  • A repository browser, so that users can inspect the contents and history of a version control repository
  • An issue tracker for managing a shared to-do list
  • Mailing lists, to help groups stay in touch
  • A wiki for creating web pages and making links to other items in Trac
  • A roadmap, for keeping track of upcoming milestones, and what's to be done for them
  • A dashboard, which graphs statistics about project progress and status
  • A timeline showing recent project activity
  • A weblog, which reports timeline events to interested parties
• These are all integrated
  • To-do items can refer to web pages, which can refer to particular revisions of files, etc.
• A single Trac installation can manage any number of projects
  • Each project's files are stored in a separate Subversion repository
  • Everything else stored in a single shared database
    • SQLite for development work and small sites
    • PostgreSQL for large sites

  • Figure 25.1: Trac Architecture

• Relies on host to handle authentication
  • Every user must have an account on the underlying Linux system
  • One less password for them to remember
• Home page looks like pretty much every other web portal's home page

  • Figure 25.2: Typical Trac Home Page

• Examine each of the components in turn below
• Comment on this slide

Repository Browser and Timeline

• The repository browser is a web-based interface to Subversion
  • Read-only: cannot update local files, or commit changes
  • Implementing this would require giving web pages the ability to mess with your hard drive
  • If you don't know why this is a bad thing, please re-read the lecture on security
• Read-only is more useful than you'd think
  • Browse directories and files to see what they contain

  • Figure 25.3: Browsing Directories and Files

  • View old versions of files

  • Figure 25.4: Viewing an Old Version of a File

  • See changes made to files over time

  • Figure 25.5: Viewing File Changes

• Following a changeset link takes you to the timeline view
  • Shows all recent project events

  • Figure 25.6: The Timeline

  • Filter control lets you select what types of events you want to see, from how long ago

  • Figure 25.7: Filtering Events

  • Very useful if you've been busy with other things for a while, and need to find out what's happened in your absence
• Comment on this slide

Issue Tracker

• An issue tracker (sometimes called a bug tracker is a tool for managing a shared to-do list
  • What needs to be done?
  • Who's responsible for each task?
  • What state is each task in?
• Essential tool for managing long-lived or multi-person projects
  • But only as useful as the information in it
  • Trac's issue tracker is simpler than most, in order to make entering data very easy
  • Most large projects use more complicated tools, such as Bugzilla
• To create a ticket:
  • Follow the “New Ticket” link

  • Figure 25.8: Creating a New Ticket

  • Fill in the fields
    • Who you are
    • A one-line title for the ticket
    • What kind of ticket it is
    • How important it is
    • When it needs to be resolved
    • A description of the issue
  • And submit
• To see what tickets are already in the system:
  • Follow either the “View My Tickets” or “View Project Tickets” link
    • The first shows your tickets across all projects
    • The second shows all tickets for the current project
  • Tickets can be sorted and filtered in various ways
• Click on a ticket to view or update it
  • All the information entered by the original author
  • A flag showing whether it is open (i.e., still needs work) or closed (completed)
  • Any comments other people have added to the ticket
    • Every time you change a ticket, you should explain why
    • Like commenting on changes you submit to version control
• Note: after updating a ticket, go back to the timeline view
  • Time of change, ticket ID, and comment are displayed
  • The display is a link back to the ticket
    • Information is more useful when it's connected
• Comment on this slide

How to Write Tickets

• A badly-written ticket is better than no ticket at all, but not by much
• The summary should be short and informative
  • Aim is to help people who are looking at 100 summaries find the one(s) they care about
  • “Bug in seq comp” is bad
  • “Seq. comparison returns wrong probabilities for bivalves” is much better
• Usually have three kinds of tickets:
  • Bugs
  • Feature requests (i.e., someone wants the software to do something it doesn't)
  • Questions
    • I.e., “Does anyone know how to parse external entities with Expat?”
    • Or, “How many old versions of Windows are we going to support?”
    • May seem odd to file these as issues, but they are for the person who's asking
    • And it's more efficient than posting them to the mailing list
• Whole team has to agree on what importance values mean
  • Low: cosmetic UI problem, minor workflow annoyance with obvious workaround, etc.
  • High: program crashes, returns wrong result, inadvertently launches nuclear assault on Iceland, etc.
  • Medium: anything in between
  • In the weeks and days leading up to a release, perform regular triage
    • Go through the open issues, and re-set their priorities so that everyone knows what they ought to be working on
• Description: provide all the information someone needs to know to address the issue
  • For a bug, need:
    • Software configuration, including package versions, operating system, etc.
    • Sequence of steps or unit test case that triggers the fault
    • Configuration files, input data, screenshots of the fault, etc.
  • Similar level of detail for feature requests and questions
  • Remember, it may be weeks or months before the issue is addressed
• Comment on this slide

Mailing Lists

• Trac assumes that everyone has a mail reader that they're happy with
• Doesn't try to compete
  • No way to compose or send mail in Trac
  • Users don't have mailboxes on the system
• Instead, Trac creates one mailing list for each project
  • Everyone who's a member of a project is automatically on that list
  • Only project members can send mail to it
• Every user must whitelist one or more email addresses with Trac
  • The opposite of blacklisting: specifies who's allowed in, instead of who's to be kept out

  • Figure 25.9: Whitelisting an Email Address

  • Trac will accept mail from any whitelisted address
  • User must specify which of those addresses to forward project mail to
  • This way, people can send from any external mail account, but all project mail arrives in one place
• Timeline shows old mail messages as well as other events
  • Not threaded by topic: unnecessary complexity for small projects
• Comment on this slide

Wiki

• A wiki is a simple web-based system for creating web pages
  • Term comes from the Hawaiian “wiki wiki”, meaning “faster faster”
• If you have logged in, and have permissions to edit the wiki, then every page has an “Edit” button
  • Clicking this displays the page source in a text edit box

  • Figure 25.10: Editing a Wiki Page

• Syntax is much simpler than standard HTML
  • Blank lines separate paragraphs
  • Any word in CamelCase is automatically interpreted as a link to a page with that name
  • = Title = creates a level-1 heading, == Subtitle == creates a level-2 heading, etc.
  • Series of indented lines beginning with * is displayed as a list
  • Anything ending in .png, .jpg, or .gif is automatically displayed as an image
• Doesn't let you do everything…
  • …e.g., you can't specify alignment of table items…
  • …but it makes it very easy to create meeting minutes, notes for first-time users, etc.
• Once you've made changes, you can preview the page, or commit the changes
  • Pages are saved in the database, rather than in Subversion
  • Translated from wiki syntax into HTML when the page is viewed
  • Note: no conflict resolution mechanism
    • If two people try to edit a wiki page at the same time, the second one to commit will be denied
    • So put large and/or frequently-updated documents under version control instead
• Wiki syntax offers shortcuts for referring to other things in Trac
  • #22 links to ticket 22
  • @41 links to email message 41
  • [94] links to revision 94 in the version control repository
  • source:path/to/filename.txt links to a particular file in the Subversion repository
    • source:path/to/filename.txt#94 links to a particular version of the file
• You can use this same syntax in:
  • Tickets (to refer to changesets, file versions, email messages, etc.)
  • Email messages (as long as your mailer sends messages as plain text, rather than HTML)
  • Subversion commit comments
  • Just about everywhere else
  • Remember, information is more useful when it's connected
• Comment on this slide

Roadmap and Milestones

• A milestone is a time by which something is supposed to be done
  • A roadmap is just a collection of milestones
• Usually give milestone symbolic names, like “version 2 beta release”
  • That way, when the date changes, you don't have a milestone called “April 1” whose due date is May 15
• Trac requires you to associate every issue with a milestone
  • Default is the empty milestone, which means “sometime”
• Can sort and view tickets by milestone
  • Moving low-priority tickets from upcoming milestone to later ones is part of pre-release triage process
• Much (much) simpler than most project management tools
  • No Gantt charts, no dependency graphs, etc.
  • They're overkill for small projects
    • Particularly research projects, which frequently change direction
• Comment on this slide

Dashboard

• The dashboard is a graphical complement to the timeline view
  • Plot changes to code, tickets, etc. over time

  • Figure 25.11: Dashboard Display

  • Allow users to compare activity in various projects
    • Has anyone been working on this project in the last few weeks?
    • Has this project's test coverage been going up or down?
  • In an educational setting, allow people to compare their projects against a class average
    • Which can be very motivational
• Comment on this slide

Blogging

• Weblogs (or blogs) started off as on-line journals
  • Author updates a file with new journal entries
    • File written in an XML format called RSS
  • Blog-reading software downloads file at irregular intervals
    • If anything has changed since the last time, display the titles of new articles

  • Figure 25.12: How Blogs Work

  • A publish-subscribe system
    • If you no longer want to read a blog, stop polling for updates
    • Helps reduce information overload
• Every Trac project creates two blogs
  • One includes only articles by people (announcements of new releases, commentary on the world at large, etc.)
  • The other also includes all timeline events
  • Project members and supervisors can subscribe to be notified of changes to files and tickets, etc.

  • Figure 25.13: A Trac Timeline Blog

• The “Compose Blog Entry” page allows project members to create entries for the announcements blog
  • Note: only people logged in to that Trac installation can comment on entries
  • Occasionally annoying, but helps reduce comment spam
• Comment on this slide

Administration

• Trac is administered from the command line, rather than through the web
  • Simpler to write and maintain
  • Makes it simpler for administrators to create a dozen accounts in a single step, etc.
• Two interfaces:
  • A standalone command-line tool called trac-admin
  • A Python library, so that administrators can write scripts to do whatever they want
• As mentioned earlier, Trac relies on underlying operating system to manage user accounts
  • Authentication is (only) as secure as your password policy
• Trac uses (person, project, permission) triples for authorization
  • E.g., (aturing, enigma, WIKI_WRITE) or (ghopper, demo, TICKET_READ)
  • Every operation requires one or more permissions
  • If there isn't a triple giving you a permission, you don't have it
• Some standard roles are pre-defined (and more can be added)
  • A role is a set of permissions
  • (jvn, funiac, ROLE_DEVELOPER) gives a user all the permissions associated with the developer role
• Comment on this slide

Summary

• And that's it
  • At least, so far—Trac is under active development
• All you need to run a small or medium-sized project
  • Very useful for geographically-distributed collaborations
  • Just as useful when one person has to manage his or her own work over the course of months or years
  • Harder to lose a database than a lab notebook…
• If Trac is too small for your needs, there are many larger alternatives
  • SourceForge is by far the most famous
  • Will host open source projects for free on their machines
• Comment on this slide

Exercises

Exercise 25.1:

Can you find out what bugs are currently being worked on? What feature requests have been deferred? Which files were changed to fix a problem? What fixes are currently being tested? How long it took to fix/implement something?

Exercise 25.2:

What is the status of the overnight build? The overnight regression tests? The issue database? The team's discussions?