Teamware

Introduction

• No programmer is an island
  • We inherit projects from other people
  • They depend on tools and libraries we didn't write
  • So you ought to think about the person who's going to take over your work before you move on
• As distributed collaboration becomes the norm, good team skills become even more important
  • All of which also make you more productive individually
• This lecture introduces core skills by showing a typical developer's day
  • Uses an open source web-based project management portal called DrProject
  • But the point is how it's used
• Send comments

You Can Skip This Lecture If...

• You know how to use wikis, weblogs, and mailing lists
• You know what an issue tracker is
• You know how to file a ticket
• Send comments

Motivation

• There's a lot more to a project than just software
  • Who's working on what?
  • When are things due?
  • What decisions did we make last week?
  • How do I install this thing anyway?
• Software project management portals like DrProject gather all this information together
  • Much of the value in information lies in the links between items
• Send comments

Architecture

• A single DrProject installation manages one or more projects
  • Each project's files are stored in a separate Subversion repository
  • Everything else stored in a single PostgreSQL database
• Relies on host to handle authentication
  • So there's one less password for them to remember
• Each user has a specific role with respect to each project
  • These roles define what people can do
• Send comments

Getting Started

• Ginny sits down to start work at 9:00 a.m. on Wednesday morning
  • Her group is working on Version 3.2 of GeneMagic
  • She spent Monday and Tuesday tracking down a bug for a group at another university who are using an earlier version of the software
  • So the first thing she wants to know is what the rest of the team have done recently
• Goes to the group's DrProject site and looks at the event log
  • 

    Figure 27.1: The Event Log

  • Chronological listing of Subversion commits, mail messages, etc.
  • Filter let her control what kinds of events she sees, and from how long ago
• Send comments

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 27.2: How Blogs Work

• A publish-subscribe system
  • If you no longer want to read a blog, stop polling for updates
• Every DrProject project's event log is also available as a blog
  • Very convenient way to keep up with several projects at once
• Send comments

Repository Browser

• Ginny notices that Ron has committed changes to a couple of files she was working on
  • Event log shows her his comments
  • But she wants to take a closer look at the changes
• The repository browser is a read-only viewer for the project's Subversion repository
  • 

    Figure 27.3: Browsing Directories and Files

  • Read-only because allowing the browser to commit files would require giving the web server permission to mess with the file system
  • If you don't know why this is a bad thing, please re-read the lecture on security
• Send comments

Viewing Revision History

• The browser can also display the revision history of a file
  • 

    Figure 27.4: Viewing Revision History

• Send comments

Viewing Changesets

• Browser can also show particular changesets
  • 

    Figure 27.5: Viewing File Changes

  • Seeing related changes together makes them easier to understand
• Send comments

Mailing Lists

• Ginny is puzzled by Ron's change, and wants to know if there was some discussion about it
  • Takes a look at the project's mailing list
  • 

    Figure 27.6: Mailing List Archive

• Send comments

Less Is More

• DrProject doesn't try to compete with existing mail clients
  • No mailboxes, and no way to compose or send messages
• Instead, it 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 messages to it
• Mailing lists aren't threaded by topic
  • Unnecessary complexity for small projects
• Send comments

Managing Mail Addresses

• Every user must whitelist one or more email addresses with DrProject
  • Specifies that mail from that address is allowed
  • 

    Figure 27.7: Whitelisting an Email Address

  • The opposite of blacklisting
• DrProject 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
• Send comments

Issue Tracker

• Now that Ginny is satisfied with Ron's changes, she wants to remind herself what she is supposed to be working on
  • As a student, she kept a to-do list in a lab notebook
    • And then in the Palm Pilot her grandmother gave her
  • But those are easy to lose, and hard to share
• An issue tracker is a tool for managing a shared to-do list
  • Each task, problem, or question is represented by a ticket in the database
  • Often called a bug tracker
• Essential tool for managing long-lived or multi-person projects
  • But only as useful as the information in it
• DrProject'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 and Roundup
• Send comments

Creating and Viewing Tickets

• Click on “New Ticket” to add a ticket to the database
  • 

    Figure 27.8: Creating a New Ticket

• To see what tickets are already in the system, follow the “View Tickets” link
  • 

    Figure 27.9: Viewing Tickets

  • Tickets can be sorted and filtered in various ways
• Send comments

When To Create, How To Use

• Create tickets for:
  • All action items from meetings are immediately converted to tickets
  • Everything that occurs to you while coding that would be a distraction from your flow
  • Any missing or erroneous installation instructions
  • Any problems you notice while chasing some other bug
• Use tickets to:
  • Make sure people are working on the right problems (tackle in priority order)
  • Create meeting agendas: going through the open high-priority bugs is a good way to keep people focused
• Send comments

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 ones they care about
  • “Bug in seq comp” is bad
  • “Sequence comparison returns wrong probabilities for bivalves” is much better
• Description must provide all the information someone needs to know to address the issue
  • Software configuration, 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.
  • Remember, it may be weeks or months before the issue is addressed
• Send comments

Other Fields

• What type of ticket it is:
  • Defect (i.e., a bug)
  • Enhancement (feature request)
  • Some other kind of task (e.g., a question that needs to be answered)
• How important it is
• When it needs to be finished
  • See the discussion of milestones below
• Who is responsible
  • Leave this as “nobody” if it's someone else's job to assign work
• Any keywords that might help with later searches
• Send comments

Updating Tickets

• Most important thing about a ticket is whether it is open or closed
  • Number of open tickets shows how much work needs to be done
    • And the rate at which new tickets are being created is a good indication of whether the project is stabilizing or not
  • It's not unusual to re-open tickets after they've been closed
    • E.g., the bug wasn't actually fixed, or the question wasn't completely answered
• Next most important thing is who the ticket is assigned to
  • Default view in DrProject only shows those tickets that are assigned to you
• Add a comment to the ticket every time you change something in it
  • Like commenting on changes you submit to version control
• Send comments

Roadmap and Milestones

• Group tickets according to milestones (due dates)
  • Milestone names are initially symbolic, 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
• The roadmap lists all future milestones
  • 

    Figure 27.10: Roadmap

  • Bars show what fraction of tickets belonging to each have been closed
  • Which is a good way to see if you're going to make the deadline or not…
• Send comments

Priorities And Triage

• Whole team must agree on what ticket priorities mean in order for them to be useful
  • 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
  • Move low-priority tickets to the next milestone
  • Make sure someone is working on every high-priority one…
  • …or that there's a workaround for the problem, or that it's mentioned in the release notes
• Send comments

Workflow

• Most issue trackers support (or impose) more complex workflow than DrProject's
  • The larger the team, the more structure is required
• For example:
  • 

    Figure 27.11: A Workflow for Larger Teams

  • Ticket is initially unassigned
  • Project manager allocate it (and specifies when it is to be completed)
  • Developer changes its status to “in progress” when she starts work
  • Marks it “ready for test” when work is done
  • QA marks it “ready for integration” once it passes tests
  • Build manager closes it once it's in the installer
  • It can also be suspended, rejected as a duplicate or irreproducible, re-opened, etc.
• Send comments

Wiki

• The only high-priority ticket assigned to Ginny is to design the new data formatter
  • She has some ideas, but wants to share them with the rest of the team before she starts coding
  • She doesn't want to start another meandering email discussion
• DrProject provides each project with a wiki
  • A simple web-based whiteboard
  • Good for storing meeting minutes, developer-oriented documentation, etc.
• Send comments

Wiki Syntax

• Clicking the “Edit” link on a wiki page brings up a text edit box
  • 

    Figure 27.12: Editing a Wiki Page

• Wiki syntax is 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.
  • Indented lines beginning with * become a point-form list
  • Anything ending in .png, .jpg, or .gif is automatically displayed as an image
• Send comments

Saving Changes

• 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
• Send comments

Tying It All Together

• Why use a wiki, rather than storing documents in Subversion?
• Because wiki syntax offers shortcuts for referring to everything else in the project
  • #22 links to ticket 22
  • [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
  • @41 links to email message 41
• You can use this same syntax (almost) everywhere:
  • Tickets (to refer to changesets, file versions, email messages, etc.)
  • Email messages (as long as you send plain text, rather than HTML)
  • Subversion commit comments
• Send comments

Rules of the Road

• Every project is different, but most successful ones follow a few common-sense rules
  • See [Fogel 2005] for a complete discussion
• Be polite: the rest is details
• Keep email messages short and to the point
  • Quote only as much of preceding messages as you absolutely have to
  • Change the subject line to reflect topic drift
  • Avoid “me too!” messages
• If it's clear that discussion isn't going to reach a consensus, call a vote
  • Just calling a vote can help clarify the question
  • +1 for “yes”, 0 for “don't care”, and -1 for “over my dead body”
  • Decide in advance whether majority wins, or whether any -1's constitute a veto
• Send comments

More Rules

• Subversion commit comments should mention tickets
  • E.g., "Fixes #456: normalizing bivalve sequences before comparison"
• Changeset IDs should appear in ticket comments
  • E.g., "Fixed in [789]"
• It only takes a few keystrokes to add this information, but the payoff is tremendous
  • When in doubt, think about what will make things easier to search for
  • E.g., add keywords to tickets to identify project components, platforms, etc.
• Send comments

Summary

• Ginny is now busy writing up her design ideas
  • Which DrProject will automatically hyperlink to old tickets, source files, and other pages
• As her team grows, it may need something larger than DrProject
  • SourceForge is by far the most famous system of its kind
  • Many people find CollabNet cleaner
• Which one you use is much less important than the fact that you use something
  • And that you remember that technology is no substitute for politeness, good will, and common sense
• Send comments

Exercises

Send comments