Printer Friendly Documentation
Below is the complete FogBugz Documentation in one HTML page.
FogBugz is a complete project management system optimized for software teams. It helps you make better software by tracking, prioritizing, and coordinating the thousands of small tasks a development team has to do. FogBugz is web based, so you access most of the functionality through your web browser.
At the heart of FogBugz is a database of cases. There are three kinds of cases:
Bugs: things which don't work right
Features: new things being planned
Inquiries: email questions from customers
Every case is prioritized, categorized, and assigned to exactly one person on your team who must either resolve it or assign it to someone else. Developers work through their cases one by one, in order of priority. Source code integration makes it easy to see which check-ins were associated with which bugs or features, and allows you to set up an elegant online code review system.
Where do cases come from?
A case can be entered by someone on your team or by an outside customer. It can be submitted via the web or through email. Email inquiries can be automatically sorted into categories. A case can be entered automatically from running software in the field. For example, if your software crashes, it can upload details of the crash to FogBugz automatically. A handy screenshot tool that runs on your Windows or Macintosh desktop lets you submit a picture of a bug to FogBugz in two clicks. FogBugz even runs online discussion groups for your customers; when a customer finds a bug or brings up a feature request, a single click creates a new case linked to the discussion.
Slicing and Dicing
The FogBugz filter feature and advanced full-text search make it easy to sort and search. You can constantly re-prioritize and reassign cases and track estimates, making it easy to track your project and ship on schedule. When a release is done you can automatically generate release notes.
Customer Email
One of the best features of FogBugz is the email management capability. When an email message comes in from a customer, spam is automatically discarded and the remaining messages are sorted into categories, based on how you train the system. Anyone on the team can respond to email and instantly see the entire history of the email conversation with that customer. Customers get an automatic email reply with a URL they can click to check the status of their inquiry. When a customer asks a common question, you can reply with a predefined snippet with as few as two keystrokes. When a customer reports a bug, via email or on a discussion group, it can easily be assigned to a developer to fix and be tracked just like any other bug. You can assign due dates and receive escalation reports to make sure customers receive timely responses.
Discussion Groups
The discussion group feature allows you to create clean, simple, and easy-to-use discussion groups for your customers. Innovative anti-spam technology prevents abuse, while a super-simple user interface encourages participation. You can even customize the appearance of the discussion groups to fit right in with your corporate web site. You can set up private discussion groups which are a great way to coordinate far-flung teams of developers and capture their knowledge permanently.
Don't Let The Documentation Scare You!
FogBugz is quite an elaborate system, and as you learn more about it, you'll be surprised at just how useful it is for managing software projects. Although we have extremely detailed online documentation, the truth is that most people will never read it—FogBugz is that easy. The documentation is designed to be an "encyclopedia of FogBugz" that you can use to look things up. If you're just getting started, it's probably enough to read one topic—The Basics of Bug Tracking—and then dive into using FogBugz. Later you can refer back to the help topics as needed if you have any questions.
FogBugz 4.0 is a major new release with huge new areas of functionality, significant improvements to basic bug tracking, and literally hundreds of small improvements throughout. These are some of the biggest new features you'll find if you're upgrading from FogBugz 3.0.
Major New Features
The new FogBugz Screenshot tool runs on your Windows or Macintosh desktop and lets you submit screenshots of bugs to FogBugz with just two mouse clicks.
Fine-grained permissions allows you to create groups based on clients or departments, and grant permissions to users in those groups.
Discussion groups for your team or customers with advanced moderation and spam filtering. You can even link discussion topics to FogBugz cases to make sure your customers are getting replies to questions they ask in the discussion group.
Due dates allow you to track urgent bugs and features, and insure that customer email gets a timely response.
RSS support lets you subscribe to any saved filter or any individual bug using an RSS reader.
Maintain release notes and compile them automatically so you can generate one of these "What's New" pages for your own software.
Automatic conflict detection warns you if you are about to submit a change to a bug that someone else changed behind your back.
Customize holidays, workdays, and working hours.
Email handling is substantially enhanced to make FogBugz the ultimate team email client. New features:
- An extremely effective spam filter filters incoming spam using Bayesian Filtering, the most reliable method known today for spam blocking.
- FogBugz AutoSort automatically sorts incoming email into categories based on the training you provide.
- Compose and track email to customers from right inside FogBugz using the Send Email menu item.
- Predefined snippets let you respond to frequently-asked questions by typing a couple of keystrokes.
- Send a confirmation email automatically to customers when mail messages are received, optionally giving the customer a URL they can use to track the status of their case.
- Quickly find other email from the same customer or domain name.
- Email threads are shown more compactly by hiding the "original message" portion of email replies.
- Automatically set a due date for responding to customer email (e.g. "within 4 business hours") and track customer email that hasn't been replied to in time.
- Better handling of large attachments.
Major Improvements
Edit filters with a click of the mouse right on the list page.
Manage saved filters just like web browser favorites.
Batch editing lets you do anything to a group of bugs that you can do to a single bug:
- Select multiple bugs on the list page with checkboxes, or, to select a group of bugs all at once, click on the checkbox at one end of the group you want to select and then shift-click on the checkbox at the other end.
- Make any change to a group of bugs (for example, change all their priorities) at once. You can even perform multiple steps (e.g. first resolve and then close a block of bugs) without having to reselect them.
A fresh new user interface that's clearer, simpler, and more attractive.
Other Significant Improvements
Integrate bug tracking with source code control software, now with support for Subversion, Perforce, CVS, SourceSafe, and Vault.
New log on method: type an email address (instead of choosing from a dropdown list) for enhanced security.
Keep track of which cases you have seen and which ones have been edited since you last saw them by using the "visited links" coloring feature of your web browser.
Automatic two way links between related cases.
Set up Shared Filters usable by all users.
The search box is now present on every page for easy access.
Customize which columns appear on the list page.
Optimized for 800-pixel wide screens instead of 640.
File attachments are now stored in the database so backup is easier.
See more than 500 bugs at once, if you really need to, using a special link at the bottom of the List page.
FogBugz preserves tabs and whitespace in bug reports for better code formatting.
Rename the "Computer" and "Version" extra fields if you have a better use for them, or hide them if you don't need them.
Sort by last modification to see the bugs that have been changed most recently.
The easiest way to understand bug tracking is to follow a bug around, for the purpose of illustration, from the moment it's born until someone finally puts it out of its misery. We'll follow the famous Bug 1203. Here's what FogBugz shows for that bug:
Here's what happened.
Mikey the Programmer is hacking away on the new FTP client feature of his groovy Macintosh software. At some point, because he's feeling frisky, he writes his own string-copy function. That'll teach them pesky reusability police! Bwa ha ha!
Bad things happen when you don't reuse code, Mikey. And today, the bad thing that happened was that Mikey forgot to null-terminate the copied string. But he never noticed the problem because most of the time he happened to be copying strings into pre-zeroed memory.
Later that week, Jill the Very, Very Good Tester is banging away at the code, rolling her forehead back and forth on the keyboard or some equally cruel test. (Incidentally, most good testers are named Jill, or some variation like Gillian.) Suddenly something very strange happens: the ftp daemon she was testing against crashed. Yes, I know it's a Linux machine and Linux machines never crash (no snorting sounds from the slashdot crowd, please) but this dang thing crashed. And she wasn't even touching the server, she was just FTPing files to it using Mikey's Mac code.
Now, Jill is a very, very good tester, so she's kept a careful log of what she was doing (the precise pitch and yaw of her head as she rolled it on the keyboard is in her lab book, for example). She reboots everything, starts with a clean machine, repeats the steps, and -- Lo and Behold -- it happens again! The Linux ftp daemon crashed again! That's twice in one day, now! Take that, Linus.
Jill squints at the list of repro steps. There are about twenty steps. Some of them don't seem related. After a bit of experimentation, Jill is able to whittle the problem down to four steps that always cause the same behavior. Now she's ready to file a bug.
Jill enters the new bug in the bug tracking database. Now, just the act of entering a bug requires some discipline: there are good bug reports and bad bug reports.
Three Parts To Every Good Bug Report
And the Lord spake, saying, "First shalt thou take out the Holy Pin. Then, shalt thou count to three, no more, no less. Three shall be the number thou shalt count, and the number of the counting shalt be three. Four shalt thou not count, nor either count thou two, excepting that thou then proceed to three. Five is right out. Once the number three, being the third number, be reached, then lobbest thou thy Holy Hand Grenade of Antioch towards thou foe, who being naughty in my sight, shall snuff it."
— Monty Python and the Holy Grail
It's pretty easy to remember the rule for a good bug report. Every good bug report needs exactly three things.
- Steps to reproduce,
- What you expected to see, and
- What you saw instead.
Seems easy, right? Maybe not. As a programmer, people regularly assign me bugs where they left out one piece or another.
If you don't tell me how to repro the bug, I probably will have no idea what you are talking about. "The program crashed and left a smelly turd-like object on the desk." That's nice, honey. I can't do anything about it unless you tell me what you were doing. Now, I admit that there are two cases where it's hard to get exact steps to repro. Sometimes you just don't remember, or you're just transcribing a bug from "the field." (By the way, why do they call it "the field"? Is it, like, a field of rye or something? Anyway...) The other time it's OK not to have repro steps is when the bug happens sometimes but not all the time, but you should still provide repro steps, with a little annotation that says that it doesn't happen too often. In these cases, it's going to be really hard to find the bug, but we can try.
If you don't specify what you expected to see, I may not understand why this is a bug. The splash screen has blood on it. So what? I cut my fingers when I was coding it. What did you expect? Ah, you say that the spec required no blood! Now I understand why you consider this a bug.
Part three. What you saw instead. If you don't tell me this, I don't know what the bug is. That one is kind of obvious.
Back To Our Story
Anyhoo. Jill enters the bug. In a good bug tracking system it gets automatically assigned to the lead developer for that project. And therein lies the second concept: every bug needs to be assigned to exactly one person at all times, until it is closed. A bug is like a hot potato: when it's assigned to you, you are responsible to resolve it, somehow, or assign it to someone else.
Willie, the lead developer, looks at the bug, decides it's probably something to do with the ftp server, and resolves it as "won't fix." After all, they didn't write the ftp server.
When a bug is resolved, it gets assigned back to the person who opened it. This is a crucial point. It does not go away just because a programmer thinks it should. The golden rule is that only the person who opened the bug can close the bug. The programmer can resolve the bug, meaning, "hey, I think this is done," but to actually close the bug and get it off the books, the original person who opened it needs to confirm that it was actually fixed or agree that it shouldn't be fixed for some reason.
Jill gets an email telling her that the bug is back in her court. She looks at it and reads Willie the Lead Developer's comments. Something doesn't sound right. People have been using this ftp server for years and it doesn't crash. It only crashes when you use Mikey's code. So Jill reactivates the bug explaining her position, and the bug goes back to Willie. This time Willie assigns the bug to Mikey to fix.
Mikey studies the bug, thinks long and hard, and completely misdiagnoses the bug. He fixes some altogether different bug, and then resolves the one Jill opened.
The bug is back to Jill, this time marked "RESOLVED-FIXED". Jill tries her repro steps with the latest build, and, lo and behold, the Linux server crashes. She reactivates the bug again and assigns it straight back to Mikey.
Mikey is perplexed, but he finally tracks down the source of the bug. (Know what it is yet? I'll leave it as an exercise to the reader. I've given you enough clues!) He fixes it, tests it, and -- Eureka! The repro case no longer crashes the ftp server. Once again, he resolves it as FIXED. Jill also tries the repro steps, discovers that the bug is good 'n' fixed, and closes it out.
Summary
The story of every bug is a variation on this theme:
- Someone finds it and reports it
- The bug gets bounced around from person to person until it finds the person who is really going to resolve it
- When the bug is resolved, it goes back to the person who originally reported it for confirmation
- If, and only if, they are satisfied with the resolution, they close the bug, and you never see it again.
- A good tester will always try to reduce the repro steps to the minimal steps to reproduce; this is extremely helpful for the programmer who has to find the bug.
- Remember that the only person who can close a bug is the person who opened it in the first place. Anyone can resolve it, but only the person who saw the bug can really be sure that what they saw is fixed.
- There are many ways to resolve a bug. FogBugz allows you to resolve a bug as fixed, won't fix, postponed, not reproducible, duplicate, or by design.
- Not Reproducible means that nobody could ever reproduce the bug. Programmers often use this to send a bug back to the tester when the report is missing the critical repro steps.
- You'll want to keep careful track of versions. Every build of the software that you give to testers should have a build ID number so that the poor tester doesn't have to retest the bug on a version of the software where it wasn't even supposed to be fixed.
- If you're a programmer, and you're having trouble getting testers to use FogBugz, just don't accept bug reports by any other method. If your testers are used to sending you email with bug reports, just bounce the emails back to them with a brief message: "Please put this in the bug database. I can't keep track of email."
- If you're a tester, and you're having trouble getting programmers to use FogBugz, just don't tell them about bugs—put them in the database and let the database email them.
- If you're a programmer, and only some of your colleagues use FogBugz, just start assigning them bugs. Eventually they'll get the hint.
- If you're a manager, and nobody seems to be using FogBugz, start assigning new features to your team using FogBugz. Eventually they'll realize that instead of coming into your office every few days saying "what should I do next?" they can just see what's assigned to them in FogBugz.
- Avoid the temptation to add new fields to FogBugz. Every month or so, somebody will come up with a great idea for a new field to put in the database. You get all kinds of clever ideas, for example, keeping track of the file where the bug was found; keeping track of how often the bug is reproducible; keeping track of how many times the bug occurred; keeping track of which exact versions of which DLLs were installed on the machine where the bug happened. It's very important not to give in to these ideas. If you do, your new bug entry screen will end up with a thousand fields that you need to supply, and nobody will want to input bug reports any more. For the bug database to work, everybody needs to use it, and if entering bugs "formally" is too much work, people will go around the bug database.
Usually when you click List in FogBugz you don't see every single case in the system: you only see a selection of the cases that match your current filter. Right at the top of the screen you can see a description of the filter:
Some of those words are underlined. By clicking on the underlines, you can pop up a little menu which lets you modify that part of the current filter quickly:
If you want to further refine the filter (for example, if you want to see only priority-one features) click on the word Filter to the left of the colon:
Note: For saved filters the word "Filter" will be replaced by name of the filter.
Click on the little plus sign next to the category by which you want to filter and choose the new filter condition.
For more precise control over the filter conditions, you can click Customize which goes to a detailed filter setup page.
Your filter will be remembered forever. Whenever you come back to FogBugz and click List, the filter will still be in place.
Next: Learn about saving and sharing filters.
Sometimes it's helpful to save filters, just like bookmarks in a web browser, so you can quickly go back to a particular list of bugs.
Once you have your filter set up exactly the way you want it, click on the Filters menu at the top of the screen and choose Save current filter as....
Give your filter a name that you'll remember. As soon as you do that, the saved filter will be instantly available from the Filters menu. Saving your filter will also save the current column layout so you'll see your filter the same way when you load it again.
To modify or delete saved filters, click on the Filters menu and choose Manage saved filters....
Shared Filters
If you are logged onto FogBugz as an adminstrator, you can create filters that the whole team can use. Simply go to the Manage Saved Filters screen, find the filter you want to share, and then click the Shared checkbox. This filter will now appear on everybody's Filters menu.
Search Results vs Filter Results
When you search for text in FogBugz, using the Search box in the top right corner, FogBugz temporarily shows you a list of bugs that match the search terms, not the list of bugs from your filter. As soon as you click List again, you're back to looking at the bugs that match your filter.
Subscribing to Filters With RSS
See RSS Notifications.
A picture can be worth a thousand words, and sometimes adding a screenshot showing a bug to your bug reports can save a lot of explanation. The FogBugz Screenshot tool runs on your Windows or Macintosh desktop. To install it, log into FogBugz and on that first page click the Capture Screenshots link in the middle of the page.
When you download and install the FogBugz Screenshot program, a bug icon will appear on your screen.
Windows:
When you click on the bug icon, it will capture the current screen.
Once you've captured a screenshot, you can crop it to make it smaller, or highlight a particular area with a red border to illustrate the exact part of the screen that represents the bug. Then you can send it to a new case or append the screenshot to an existing case.
Tip: By right clicking on the screenshot tool, a menu appears allowing you to enter a bug directly without capturing a screenshot. This is the fastest way to launch your browser and go to the New Case page.
To uninstall the FogBugz Screenshot tool: first quit the program by right clicking on the screenshot icon shown above and selecting Exit, then use the Add or Remove Programs feature in the Windows Control Panel.
Capturing a screenshot makes a camera shutter sound. To turn off this sound, click Sound:OFF in the bottom right corner of the Screenshot window.
To change the URL where screenshots are sent, click on the URL at the bottom of the screen. By default, this is set correctly, but if you use more than one bug tracking database, you'll have to adjust this. Use the basic URL of FogBugz, including http://, but without any file name. For example, http://www.example.com/FogBugz
Macintosh:
When you click the bug icon, you will have a choice of capturing a window, a rectangle, or the whole screen. After capturing, you can highlight a particular area with a red border to illustrate the exact part of the screen that represents the bug. Then you can send it to a new case or append the screenshot to an existing case.
Capturing a screenshot makes a camera shutter sound. To turn off this sound, click Sound:OFF in the bottom right corner of the Screenshot window.
To change the URL where screenshots are sent, click on the URL at the bottom of the screen. By default, this is set correctly, but if you use more than one bug tracking database, you'll have to adjust this. Use the basic URL of FogBugz, including http://, but without any file name. For example, http://www.example.com/FogBugz
FogBugz has several features allowing you to keep a handle on your development schedule:
-
Priorities from 1-7 let you decide what gets done first.
-
Releases lets you decide which case will be fixed for which upcoming release of your software. You can also gather
Release Notes. Each case also has a
Version field to track where a bug was first seen.
-
Estimates let you provide detailed estimates for how long a case will take to resolve in hours or days, and how much time has already been spent on it.
-
Due dates let you add a specific due date and time to a specific case, and insure that customer requests are responded to promptly.
You can create a hyperlink from one case to another very easily: just type the word "case" followed by the number of the case to link to.
For the purposes of this description, let's say you're entering comments in case 10. If you type "see case 20", FogBugz will turn "case 20" into a link to case 20. (If you like, you can use the word "bug" instead of "case").
Not only does this create a link to case 20 within case 10, but when you view case 20, you will see case 10 listed as a "Related Case". (This, of course, is a clickable link back to case 10.)
When one bug report is a duplicate of another bug report, you should resolve it as "Resolved (Duplicate)". That lets you enter the number of the bug that it is a duplicate of, and this becomes a hyperlink. Once again, this link goes both ways between the cases.
Working Through a List of Cases
Often, you want to work through a list of cases—checking that they are assigned to the right person, re-evaluating their priorities, etc. FogBugz makes this easy in a number of ways.
Next/Previous Buttons in Cases
There are Next and Previous buttons in the top right corner of the case, which show the next or previous case in your current filter:
-
Note: If you change the case's position in the filter while you work through the list, you may be confused by the behavior of the Next button. For example, if your filter lists cases in order of priority, and you change a case's priority to be higher, clicking Next will take you to a case you've already seen. The easiest way to prevent this is to use a stable sort order, for example, sort by Case ID number, which won't change as you work through the list.
If you're using keyboard shortcuts, then after hitting Ctrl-; you can use the [ (left square bracket) and ] (right square bracket) keys as shortcuts for Previous and Next.
Link Colors in Lists
Another thing to notice is that FogBugz carefully coordinates with your web browser to insure that bugs you've already seen are shown in the "visited links" color (usually purple) while bugs you haven't seen are in the "unvisited links" color (usually blue).
This makes it easy to work through a list of bugs by returning to the List page and clicking on the next blue link in the list. Lather, rinse, and repeat until they're all purple.
The cool thing is that FogBugz will change the URL for any bug that changes after you last saw it. That way, if anything changes about a bug that you've already looked at, the link to that bug will go from purple back to blue again.
Receiving Notifications of Changes to the List
FogBugz publishes RSS Feeds allowing you to use an RSS Aggregator to receive notifications, so you can keep up to date on changes to your filter without opening your web browser. Read more on RSS.
Open All Cases, Each in its Own Browser Tab
The Firefox browser supports both RSS and tabbed browsing which, combined with FogBugz RSS feeds for saved filters, allow for a very time-efficient way to walk through every case in a list. For example, this is ideal for a list of incoming customer emails that all need to be answered.
The screenshot above shows a saved filter named "1 - Incoming" (the numeral "1" is just there so that this filter shows up first in the list of saved filters). Because it is a saved filter, FogBugz creates an RSS feed. Because FogBugz creates the RSS feed, FireFox displays a small orange RSS button at the bottom right corner of the browser window. You can click that button and select Subscribe to '1 - Incoming':
Choose "Bookmarks Toolbar Folder" so that it will show up as a button on the browser toolbar. Give it a short name like "Incoming" so as not to take up too much space on the toolbar. If you click on this new Incoming button in your browser, you see the list of cases. Fine, that's not exciting because you already have the list of cases, but here's the nifty time-saver: right-click on the Incoming button and choose "Open in Tabs", and you're given every case in the list displayed each in its own tab:
Once you click "Send and Close", you can hit Ctrl-W to close that tab rather than waiting for FogBugz to reload the list page in that tab.
The main advantage of this whole approach is just to eliminate waiting for page loads. To keep it from going out of sync with the actual list, you will need to right-click the Incoming button and choose "Refresh Live Bookmark" every now and then.
FogBugz lets you do almost anything to a bunch of bugs that you can do to a single bug. Simply set up the filter that includes all the bugs you are interested in, go to the list page, check off the bugs you want to manipulate, and click on the appropriate action button.
To select any range of consecutive bugs, check the first box, then hold down the Shift key and check the last box.
Be patient; batch editing can take a while if you have selected a lot of bugs.
Tip: Clicking on the checkbox in the column header selects or unselects all the bugs on the page.
FogBugz publishes RSS feeds, allowing you to use an RSS aggregator to receive notifications, so you can keep up to date on changes to your filter without opening your web browser. FogBugz supports RSS version 2.0.
Note: An RSS ("Really Simple Syndication") reader or aggregator is a program that checks with a bunch of websites to see if there's anything new there, and shows you a list of new items on all the sites in one central location. That way you don't have to visit sites that haven't added anything new since the last time you looked. Many websites, including popular news websites and most weblogs, publish RSS feeds so that RSS aggregators can find out if anything new has appeared.
FogBugz creates an RSS feed automatically whenever you save a filter. For the RSS link, go into the Manage Saved Filters screen. You will see a little orange RSS link next to every saved filter. Copy the link location into your favorite RSS aggregator.
Note: Some RSS readers may not support cookies, making it impossible for them to keep you logged on to FogBugz. To work around this problem, you will need to append your user name and password to the end of your feed link manually:
(FogBugz-generated RSS link)&sEmail=email&sPassword=password
You can also subscribe to a single bug using RSS, which will notify you as that bug changes, just as subscribing by email would. Simply enter the URL of the bug itself in your RSS aggregator, which will automatically discover the URL of the RSS link for that bug. The URL of bug number 1234 is http://fogbugz/?1234 where fogbugz is your main FogBugz URL. (If your aggregator cannot automatically find the RSS url, you can enter it manually as http://fogbugz/rss.asp?ixBug=1234)
For a time-saving tip on using a tabbed browser to display each case in a list in its own tab, see this article.
The Options page lets you configure your personal options in FogBugz. Anyone who is logged on as an administrator can change the options for any user; everyone else can only change their own options.
You can configure:
- Your full name as it appears in FogBugz.
- Your password.
- Your email address. If you wish to receive multiple copies of each notification email at different addresses, separate the addresses by commas.
- Your phone number.
- Whether you will receive automatic email notifications.
- Whether you are subscribed to a morning escalation report listing all cases which are past due or due that day.
- The keyboard shortcut used for snippets. By default this is set to `, but if you are using a non-US keyboard there may be other keys which are easier to type.
If you are an administrator, you can also use the Options page to configure the following user options:
- Whether the user is an administrator or not.
- Whether the user account is active or not. An inactive account can't be logged into and won't count against the total number of licenses you have purchased for FogBugz. For example, if an employee leaves the company, you can deactivate their FogBugz account and free up that license for another person.
At the bottom of every case page is a link that lets you subscribe to that case. This will send you an email notification whenever anything changes about that case.
In the interest of reducing the amount of unwanted email, FogBugz does not let you force-subscribe someone else to a case. If you want them to know about it, you should temporarily assign the case to them with a note like "FYI" (which sends them a notification email) and then immediately assign it back to whomever it really belongs.
There are three other ways to get notifications when cases you're interested in have changed:
-
You can subscribe to a case using
RSS.
-
The "visited" link color (purple) on the List page will change to the "unvisited" color (blue) if anything has changed about the bug since you last looked at it.
-
You can subscribe to a daily escalation report in the Options screen; the daily escalation report is emailed every morning and lists all overdue bugs and all bugs which will become due that day.
Also note that FogBugz will always tell you:
- if someone has assigned a bug to you
- if someone has changed a bug which is already assigned to you
You can turn off email from the Options screen, but this is probably not a good idea. You should only turn off email if:
- You already spend so much time in FogBugz you won't miss new cases assigned to you
- You are setting up a virtual account that doesn't correspond to a real human to hold bugs temporarily for one reason or another
FogBugz can be integrated with popular source control systems. This creates a two-way link: when you're looking at a bug, you can see the list of code changes and check-ins associated with it, and when you're looking at a check-in, you can see which bug it was meant to fix.
If you don't already have source control, Fog Creek Software highly recommends Subversion. It's free, and available from http://subversion.tigris.org/. On all but the largest projects, it works just as well as more expensive source control systems and is extremely reliable. If you need more convincing, check out the screenshots here which show the 360 connections between FogBugz and Subversion.
Virtual Tour
We have a thorough step-by-step tour of this integration showing screenshots from either CVS, Perforce, or VSS.
Setup
Read on to set up integration with CVS, Subversion, Perforce, VSS, or Vault.
FogBugz incorporates extensive features for receiving, tracking, and responding to customer email.
How it works:
- A message arrives in a mailbox on your mail server.
- Periodically, FogBugz uses the POP3 protocol to check your mail server for new messages.
- If any messages are found, FogBugz downloads them from the mail server and creates a case out of each one.
- If you're using the AutoSort feature, FogBugz discards spam and sorts the rest of the messages into areas according to topic.
- If desired, FogBugz sends an immediate reply to the customer, providing them with a URL they can use to check on the status of their request.
- Once the message is in FogBugz, you can treat it like any other case: you can prioritize it, assign it, track it, slice it, dice it, deep fry it, etc.
- At any time you can reply to the message from within FogBugz. FogBugz will insert the case number into the subject line of the outgoing message.
- If the customer responds to your reply, as long as they don't remove the FogBugz case number from the subject, their response will be appended to the current case rather than opening a new case.
- FogBugz will keep a complete transcript of everything that happens with the case, including all relevant incoming and outgoing email and even private internal conversations about the case which the customer does not see.
You can use FogBugz email integration to manage customer service or a helpdesk. FogBugz can set automatic due dates on incoming email so you can be certain that customers are receiving replies to their email inquiries in a timely fashion.
Another use of FogBugz email integration is to create a customer bug-reporting address or a suggestion box. Since all customer emails go right into FogBugz, you can treat them just like bugs or features: assign them to developers, schedule them, assign priorities and due dates, and so on. When the feature is implemented or the bug is fixed, with one click you can reply to the customer to notify them of this. You can also bulk-reply to several customers, for example, if they've all written to you about the same incident.
Note that the public can also submit new cases via "public projects", and can post on public forums (you can turn a forum post into an internal case with one click).
To learn more about managing customer email, read these topics:
FogBugz gives you full-fledged discussion groups built in.
Discussion groups can be private or public.
Private discussion groups are a great way to communicate in your team. Unlike private email, once conversations are captured in a discussion group, they will always be visible and searchable, capturing valuable development knowledge for posterity.
Public discussion groups are a great way to communicate with your customers and provide tech support for customers. The biggest advantage of communicating with your customers over a discussion group instead of email is that you won't have to repeat yourself so much, and there's a good chance that your customers will help each other solve problems before you have a chance to get to them.
FogBugz even lets you link items in discussion groups to cases, so you can make sure somebody deals with each customer problem, bug report, and feature request.
To learn more about Discussion Groups, see:
What is BugzScout?
BugzScout is a system which allows you to send new bugs directly to FogBugz simply by submitting an HTTP post. This is a great way to automatically report bugs into your database. This article first provides a brief overview, lists the BugzScout-related files included with FogBugz, and then provides some brief descriptions of the basic features that you may find helpful. The BugzScout system is supported on all server platforms that FogBugz is supported on.
See also Get Crash Reports from Your Users - Automatically, an article by Joel Spolsky about gathering crash reports from your customers.
BugzScout allows your program to report bugs back to your FogBugz server. For example, when your code is in beta, you may want to let users send you feature requests, and you certainly want to gather data about crashes.
Included in every FogBugz installation is a URL called scoutSubmit.asp (or scoutSubmit.php on non-Windows installations). This URL is the entry point for automatic bug submissions and is all you need in order to use the BugzScout system. When you need to submit a bug report from the field, you simply create an HTTP post containing the values that scoutSubmit.asp expects to receive, and post that directly to scoutSubmit.asp on your web server.
Your web server must be on a server visible from the Internet. If it is behind a firewall, you can configure that firewall to forward HTTP requests to the FogBugz server. The only file that needs to be publically accessible is scoutSubmit.asp. You may choose to configure your web server so that this is the only file accessible to the world, while keeping all the other files in the FogBugz directory protected.
How Are These Bugs Handled within FogBugz?
Duplicate Bug Submissions - If the description field of a bug submitted via scoutSubmit.asp matches exactly to any existing bug, the following occurs:
- This new submission will be appended to the existing bug's history, and a new bug will not be created in FogBugz. So if one bug is reported by 1,000 copies of your program, only one case will be created in FogBugz for this bug. (You can over-ride that behavior if you set ForceNewBug to 1 or "true".)
- The occurrences field for the existing bug will increase by 1. (The occurrences field of a bug, e.g. "3 occurrences", appears only when there is more than one occurence of that bug.)
- FogBugz will return a status message to the person who submitted the bug. If there is already a case in FogBugz with the same description as this new bug, and that case has a "Scout Message" specified, that message will be returned to the customer. Otherwise, the ScoutDefaultMessage text will be returned to the customer. An example of a default message could be something general like "Thank you, your bug report has been received", or it could contain instructions for a workaround for this bug.
When you edit a bug submitted via scoutSubmit.asp, the case will have two new fields:
- Scout Msg
Type in a custom message to be returned to the next person who submits this same bug, i.e. if and when a bug with the same description is submitted again. You could use this to provide the user with instructions for a workaround for this bug, or tell the user that this bug has been fixed for the next release.
- Scout Will
This controls whether or not future duplicates of this case will be appended to this case. If it is set to "Stop Reports", future submissions with the same description will not be added to FogBugz in any way. "Continue Reporting" simply means that future duplicates will continue to be appended to this case.
Sample Files
In the Accessories directory of FogBugz for Windows there is a file named ScoutSample.zip that contains examples of how to use BugzScout. There is a BugzScout mini-app that submits HTTP posts to scoutSubmit.asp for you (available in both C# and C++ incarnations), and there is ScoutSample (available in both C# and VB) which provides examples of how to use BugzScout. Source files are included for everything, with helpful comments (particularly in the C# files). Click here to see the interface to ScoutSample (VB version shown), with usage tips for the fields involved.
For readability, please make sure your Description field uses a carriage return / line feed line separator. For example, you could do this before submitting the report to BugzScout if you need to get the CRLF in there: Replace(strCrashReport, "\n", "\r\n").
Following is a brief description of the key files and folders in ScoutSample.zip:
.Net/C# version:
- BugzScout.Net\BugzScout
A .Net object version of BugzScout, including C# VS.Net Project source files.
- BugzScout.Net\BugzScout\bin\Release\BugzScoutDotNet.dll
The compiled C# BugzScout .Net object.
- BugzScout.Net\ScoutSample
A C# project that uses the BugzScout .Net object. Use this as an example of how to submit cases to FogBugz from your own code, reporting the stack trace and other helpful information.
- BugzScout.Net\ScoutSample\bin\Release\ScoutSample.exe
Double click on this to see BugzScout in action. This is a simple Windows program that collects information from the user and passes it to BugzScout, which in turn submits the new case to FogBugz.
C++ and VB version:
- BugzScoutCPP
A C++ ActiveX object version of BugzScout including source files.
- BugzScoutCPP\howto.html
Instructions specific to the C++ ActiveX version, and example VB code with documentation.
- BugzScoutCPP\ScoutSample
A VB project that uses the C++ ActiveX object. Use this as an example of how to submit cases to FogBugz from your own code.
- BugzScoutCPP\ScoutSample\ScoutSample.exe
Double click on this to see BugzScout in action. This is a simple Windows program that collects information from the user and passes it to BugzScout, which in turn submits the new case to FogBugz.
HTML example:
- BugzScoutCPP\ScoutSample\scoutsample.html
A sample HTML form which publishes the relevant info to FogBugz. This file explains the different variable arguments to the scoutSubmit.asp file in your FogBugz install. You could customize it to allow users to submit bugs directly through an HTML form.
FogBugz lets you group projects by client, which is helpful when you work with multiple clients, each of which may have multiple projects. You can also group projects by department, which is helpful when your team is divided into different departments, each of which may work on multiple projects. Clients and departments are treated in exactly the same way: they're both ways to group projects.
To group projects by client, log on as Administrator and go to the Clients page. Set up your clients. Then edit each project in turn, assigning it to the appropriate client.
To group projects by department, log on as Administrator and go to the Departments page. Set up your departments. Then edit each project in turn, assigning it to the appropriate department.
Each project can be assigned to exactly one client or one department, but not both.
There are two reasons to group projects by client or department:
- Doing so allows you to create a filter which lists all cases for a certain client or all cases in a certain department that you care about.
- User access can be granted on a client or departmental level. This means it will be possible to create FogBugz accounts for your clients such that they can only see their own cases. You can also partition departments so that users can only see cases in their own department. For more about this, see Permissions.
FogBugz displays a picture of the day, which appears on the FogBugz home page and in the list of bugs if you're in List View mode.
These pictures are rotated daily from a selection found in the website\pictures subdirectory of your FogBugz installation on the server. You can replace those pictures with your own selection. Each picture should be 196 pixels wide but can be any height.
by Joel Spolsky
I used to work as a developer on the client software for one of the largest American ISPs. Our software was used by literally millions of people. Even the rarest bug had the potential to affect hundreds or thousands of users. Yet I felt extremely confident when we decided to push the button releasing our latest code. I remember telling my dad, "The beta is looking great; yesterday we only had twelve crashes in all of North America."
Twelve, huh? Not, say, thirteen?
Nope. Twelve. We were using an increasingly popular technique of collecting crash reports from the field automatically, and summarizing them in our bug tracking database, allowing developers to find and fix bugs that only happened in the field. These were usually the kinds of bugs we would never have caught in the test lab, since we couldn't possibly reproduce every bizarre PC configuration our customers might have.
This crash detection and reporting is starting to become more common. Now that Internet Explorer and Windows XP have it built-in, customers are starting to expect their desktop software to take care of reporting its own crashes.
The confidence you get from finding out about every crash, anywhere in the world, is crucial to delivering a high quality product that needs to be used in the wild. For those of us in the consumer software business it's absolutely critical. You can't rely on your customers to tell you about crashes—many of them may not be technical enough, and most of them won't bother to take time off of their own important work to give you a useful crash report unless you make it completely automatic.
Now that I have my own company, I'm a big believer in this technique. Virtually all the code we write at Fog Creek Software has some way of reporting errors back to the development team via our FogBugz bug tracking database. That includes code that we ship to customers, such as CityDesk, a Windows application, and FogBugz itself, which is a web-based application that our customers install on their own web servers. Both of them report crashes via the Internet. Even software that we write for internal use only, such as the e-commerce software that runs the Fog Creek online store, notifies the development team if a crash occurs.
Anatomy of a Crash
OK, so your code crashed. In almost every programming environment, there's some way to recover from the crash at a central location. At this point, instead of letting the program die, we display a dialog box (see Figure 1).
Figure 1: Our automated crash reporting dialog box is short and to the point.
One thing I've learned over the years is that the more questions you ask people, the less likely they are to answer. So we only ask the bare minimum number of questions that we think will help us diagnose the problem. What were you doing? What is your email address? We emphasize that providing an email address is optional, to alleviate privacy concerns. It's amazing what superstitions persist: in the consumer marketplace, there are lots of people who have been taught by the 11 o'clock news never to give out their email address, to avoid spam, and if you require an email address some percentage of these people just won't send in the report.
Almost any other information that you consider important can probably be obtained automatically, for example, what version of operating system they are using, how much RAM they have, etc.
It's important to emphasize the anonymity and privacy of this crash submittal. People working on confidential data may not be willing to submit a crash report if they suspect we're about to upload all their sensitive work, so we provide a link that users can click on to see exactly what we're going to transmit. To avoid even the appearance of impropriety, be careful to tell people about any automatically gathered information that you're transmitting, too.
Collecting Data
The next question is, what data should we collect that will help our developers find the crash? There is a temptation to grab everything. Every bit of system information you can find. The versions of every DLL and COM control on the user's system. Even a complete memory dump (a.k.a. core dump).
After several years working as a developer and never quite knowing what I'm supposed to do with core dumps, I have discovered that collecting this data is not, actually, necessary. Instead, here is the data we collect:
- The exact version of our product
- The OS version and the version of Internet Explorer. (So many parts of Windows are actually provided by Internet Explorer and its components that this is important even for GUI applications.)
- The file and line number in the code where the crash occurred
- The error message, as a string
- A unique numeric code for this type of error
- The user's description of what they were doing
- The user's email address
That's it! Over the years we've found that knowing the exact line of code where the code crashed is enough information to fix almost any crash. For those rare cases where this isn't enough information, you can contact one of the users who experienced the crash via email and ask for any additional information that might help. The benefit of gathering so little information is that the crash reporting process is very fast, making users less impatient. Just checking the version numbers of all the DLLs and COM controls can take quite a while, especially when you factor in the upload time over modems, and very rarely provides useful information. Even if you discover that a certain crash only happens with a certain version of one of Microsoft's system DLLs, what are you going to do about it? You still have to fix the code to work around the crash.
Phoning Home
Thanks to the pervasiveness of the Internet, there's almost always one best way to send the information home: over the web. By sending a standard HTTP request, you will get your bug report past almost any kind of firewall customers may have in place. Virtually every programming environment now has built-in libraries to send an HTTP request and get the response back. For example, on Windows, there are built in functions in the WININET library that use Internet Explorer's network transport code to send an HTTP request and get the response. The best thing about these functions is that even if the user has configured his web browser to go through a proxy server, which is common inside firewalls, the WININET calls will automatically go through the proxy server, with no additional work on your part.
For the response part of the HTTP request, our FogBugz server returns a super short XML file which indicates that the report was received, and includes a message which is displayed to the user. More about that in a moment.
If your application is web based, there's something even easier you can do: display a web page containing a form that submits data to your server. It's as simple as changing the action attribute of the form tag to point to a URL on your bug tracking server. See Figure 2.
Figure 2: the web page that appears when FogBugz is about to crash. The HTML for this page contains a form which sends the complete crash report to a URL at Fog Creek Software that collects the crash data.
For certain types of applications, instead of sending the crash report right away, you may want to try writing it out to a file or the registry, and then sending it the next time the user launches the program. I call this technique delayed transmission. Although this will delay the report a bit, it has the advantage that if the crash was severe enough that the application is too messed up to transmit a bug report, you'll still get the report.
All crash reports arrive at Fog Creek via a single URL on our public-facing server. Our bug tracking database receives bug reports via this unique URL. In fact that URL is the only public access to our database; everything else is locked out, so people can submit bugs, but they can't get into the database.
Figure 3: What a bug reported by BugzScout looks like in FogBugz. Note the BugzScout-specific fields "Scout Msg" and "Scout Will", shown highlighted.
Figure 3 shows what a bug looks like when it arrives in our database. We could have set it up so that the bug report automatically goes to a designated member of the development team, but these days rather than interrupting one person, we've set up a virtual person called "CityDesk New Bug." Every once in a while when we want to sift through crash reports, we can just search for all bugs assigned to this virtual person, and decide whether to fix them or not. The ones that we decide to fix are then assigned to a real person.
Identifying Duplicate Crashes
An important aspect of automatic crash collection is that the same crash will probably happen many times to many people, and you don't really want a new bug in your database for every duplicate of the crash. We handle this by constructing a unique string that contains key elements of the crash data.
We are careful to construct this string in a way such that two people with the same crash generate the same string. After some experimentation, we found that the best way to do this is to include the error number, file name, function name, line number, and the version of our software in that string. In Figure 3, the unique string is "Error 91 (global:IsRoot:0) V1.0.32". That means error number 91 occurred in the file named global.bas, in the function IsRoot, on line 0, running version 1.0 of the software, build 32. Incidentally, we always use even build numbers for internal builds that we don't send out to customers, and odd build numbers for all builds that go to customers, so I can tell at a glance that this particular crash happened to a developer and not to a customer.
FogBugz will automatically append future crashes with the same unique string to this case, rather than opening a new case. This helps the programmer see all the duplicates of the same crash in one place.
Designing the format of the unique string can be tricky. In the past, we included the entire text of the crash error message in this string. However, we soon discovered that the error message was translated into different languages. So for every crash report, we would find out about it separately in English, German, Spanish, French, and a few other languages I can't identify! We solved that problem by putting the error message in the body of the crash report but only putting the unique error number in the title, which doesn't vary from language to language, so we get far fewer dupes.
We also set up the title in such a way that it can be easily searched for particular problems. Since we use the format filename:function:lineNumber (note the colons) in the title, it's easy to search for bugs in a particular function just by searching for ":function:". We prepend the letter V to our version number for the same reason; you can search for V1 or V1.0 or V1.0.32. If we had left out the V, a search for version 1 would yield every bug report that happened to have a 1 anywhere in the title.
Once the bug is identified, we can change a flag (Scout Will in the FogBugz interface) from "Continue Reporting" to "Stop Reporting" after which future crashes with the same unique string will just get ignored. We can even set a text message (Scout Msg in the FogBugz interface appears for automatically submitted cases) which will be sent back to all users in the future who have this crash. We use this to suggest workarounds when we've found them. Like, "Hey! Next time don't forget to pat your head and rub your tummy before you save!"
One common cause of duplicate reports is when a crash occurs in the crash handling code itself. This doesn't necessarily mean the crash handling code is buggy - it might just be because the original crash has scrambled something so badly that no code can run successfully any more.
Debugging
During beta testing periods, we try to look at each crash report right away. When the user provides their email address, developers can hit the Reply button in FogBugz to send them an email message on the spot if they need additional information. FogBugz automatically keeps a copy of all the correspondence related to this bug, incoming and outgoing, in the bug report itself.
Once the product is shipping and developers are working on the next major release, they usually can't find time to look at every incoming crash report. Instead we tend to wait a few months to see what crashes are most common, and we only work on the crashes that occurred most often. The disadvantage is that you can't really correspond with a user asking questions about a crash they had several months ago: they just won't remember enough details. But I've found that if the same crash has happened several times, inevitably one of the users has given me enough clues about what they were doing that I can repro the bug in the lab. Indeed, it's very rare to know that a given line of code has crashed without having a good idea for what the problem might be, even if it's hard to figure out the repro case. Once I literally worked my way backwards through the code doing arithmetic and using applied logic to figure out repro steps. Hmm, if this is crashing, then this value must be negative. If it's negative, then this IF statement must have been true. And so on, until I figured out what combination of values led to the crash and realized what must have caused them.
Triage
As soon as you build an automatic crash reporting system, you're going to get a pretty steady stream of crash reports. So good triage skills - deciding which bugs are most important to fix, and ignoring the others - are more important than usual.
CityDesk has about 20,000 copies in use and most of our customers tell us it's rock solid, but still we get a couple of crash reports every day, but many of them only happened once. When I investigated these, I usually discover various signs of bugs that we're probably never going to fix. For example:
- The user's computer is failing or has faulty RAM
- The user is experimenting by manually editing our files
- The user is running an old operating system like Windows 95 that is in the advanced stages of crashing
- The user is running our program under severe low memory conditions, possibly with a full disk and full memory
And sometimes, you just can't figure out what caused the crash. Especially with crashes that only happened once. That's life. It's important not to get too bogged down in fixing every crash you see. You can get a lot more bang for the buck by focusing on the common crashes. In fact my policy is that I won't even look at a crash that only happened once. We've got bigger fish to fry. If it's not reproducible in the field, it's not likely to be reproducible in the lab.
Shrink-wrapped Versus In-house Software?
So, now that you've seen what's involved, is crash reporting for you? The answer, to some extent, depends on your user base.
If you're developing shrink-wrapped or consumer software, quality is, quite literally, a competitive advantage. And your software will be running in a hostile environment. Consumer PCs are a mess. No two are the same. They've all got slightly different hardware and software configurations. PC companies ship these things with every imaginable piece of junkware preinstalled. And a lot of consumers gleefully download and install every shiny new object they can get their hands on, including those oh-so-clever utilities that actually inject themselves into the process spaces of other running applications. And most home users don't know enough about computers to keep their systems operating well. In such a hostile environment, automatic crash reporting is the only way to get to the level of quality that the market demands.
On the other hand, if you're developing corporate software for in-house use, you're probably not going to get as much value out of automatic crash reporting. Corporate software is usually written to solve a particular problem, at great expense relative to off-the-shelf software. Once the problem is solved, it's not worth spending any more money on that particular project. If the code crashes once a week, it can be annoying, but there may be no business justification to spend several thousand dollars having a developer fix it. It might be nice but it would not be profitable. Idealistic software developers on in-house projects are often disappointed to discover that as soon as their code is "good enough," their managers tell them to stop working on it. It has solved the business problem, even if the quality could be better, and any marginal work has zero return on investment. Still, many corporate software developers are forced to work literally without any QA or testing staff at all, and automatic crash detection may be the only way to get any kind of bug reports at all.
In conclusion, building a robust system to handle crashes from the field, report them, classify them, and track them will delight your customers and pay for itself many times over in the quality of code that you ship.
How Do I Get This Working With FogBugz?
Included in every FogBugz installation is a file called scoutSubmit.asp (that's scoutSubmit.php in non-Windows versions of FogBugz). This file is the entry point for all automatic bug submissions. You can create an HTTP post with the correct form values and post directly to this file on your web server. Alternatively, you can use our free BugzScout ActiveX control which will package up the values for you and submit them via HTTP to your FogBugz installation. See the this article for more details about the BugzScout files that are included with FogBugz.
Appendix One: Handling Crashes in Visual Basic Code
Because a typical Visual Basic 6.0 event-driven program has so many entry points (one for each event that you handle), the only way to catch crashes which occur anywhere in the code is to add error handling to every function. Here's what all our functions look like:
Private Sub cmd_Click()
On Error GoTo ERROR_cmd_Click
' the actual code for the function '
Exit Sub
ERROR_cmd_Click:
HandleError "moduleName", "cmd_Click"
End Sub
Adding this code can be a pain; luckily there's a utility you can get called ErrorAssist which will add error-trapping code to all your functions automatically. In every case, we just call a global function called HandleError which displays our custom crash dialog. The crash dialog contains the BugzScout ActiveX control. This is a small ActiveX control which comes free with FogBugz, which can be used to transmit bug reports into a FogBugz bug tracking database.
Appendix Two: Handling Crashes in Windows API Code
The Win32 API contains a concept called structured exception handling. When a crash occurs, Windows searches for the current unhandled exception handler function and calls it. If there is no unhandled exception function, it will display the usual user-aggressive "This program has performed an illegal operation" dialog box.
To install your own unhandled exception function, you have to do two things. First, implement your own function of the form
LONG UnhandledExceptionFilter( STRUCT _EXCEPTION_POINTERS *ExceptionInfo );
Then call the SetUnhandledExceptionFilter function, passing in a pointer to your UnhandledExceptionFilter function.
Another way to accomplish the same thing from C++ code is to surround main entry point with a __try/__except clause. Notice the two underlines which cause the compiler to handle structured exceptions which come from low level failures like dereferencing null pointers, not the garden variety C++ exceptions you throw yourself and handle with try and catch.
Search for Using Structured Exception Handling in the Windows Platform SDK or MSDN for more details.
Appendix Three: Handling Crashes in ASP Applications
Microsoft's Internet Services Manager lets you set up a custom error handling page, either HTML or ASP, which is processed for any scripting errors that aren't handled with On Error statements. In particular, when an ASP (Active Server Pages) application crashes or has an unhandled error of any sort, the page is redirected to the error handler for "500;100" errors. In all our applications, we have an ASP page set up to catch 500;100 errors.
That page contains the following key bit of VBScript code:
Set objASPError = Server.GetLastError
Now you'll have an object called objASPError which contains lots of useful data about the crash that just occurred, including the file and the line number.
Sample code for handling ASP errors comes preinstalled on every computer with IIS: look in the \windows\help\iishelp\common directory for a file called 500-100.asp. This simply displays the details of the ASP error to the end-user. Using the 500-100.asp file as a starting point, you can create your own customized message page, containing a form with hidden elements containing the crash data. The form should have an action attribute which submits all the error information to another web page. If you're using FogBugz, you just direct the form to
http://<your FogBugz URL>/scoutSubmit.asp
to open a new case in your bug database.
Note: The latest documentation on FogBugz setup is always maintained at the Fog Creek Website, where you will also find an extensive knowledge base and an online discussion forum.
Learn about setting up the FogBugz server on:
FogBugz allows you to set up permissions (access control) so that only certain users can see or modify certain cases. Before you can start assigning permissions, you need to create a client or department.
Typically, you will use FogBugz access control for two purposes:
- If you have multiple external clients, you can give them all accounts on your FogBugz database without letting them see each other's cases, or even know about each other. When your client logs on to FogBugz, they will only be able to see cases associated with their projects, not with the projects of other clients. They won't even be able to find out about the other clients: they will have no way of seeing cases or users or projects unless you specifically grant them permission.
- If you are using a single FogBugz installation for multiple departments, you can set things up so that users only have permission to see cases in their own department.
FogBugz will give a particular user permission to access all the cases associated with a particular client or department. This means that before you can start assigning permissions, you need to create a client or department.
Example One: A Consulting Firm.
Beverage Gurus Inc. has three clients: Coca Cola, Pepsi, and Tastes Like Tar Cola ("TLT"). Each internal consultant is only allowed to see cases for the client they are working on. Personnel from the client companies are sometimes given accounts on FogBugz. Of course, they can only see cases related to their own projects.
Beverage Gurus does not want their Coca Cola clients to be aware that Pepsi is also a client of Beverage Gurus. Sneaky gurus!
Whenever FogBugz shows a dropdown list of users, it will not include everyone. It will only list users that you might encounter because you share permission to access some client. For example, consultants Alice and Bob are working on the Coca Cola account only, while Mike is working on the Pepsi account only. Normally, Alice and Bob will see each other in the user dropdown, but they'll never see Mike's name in a dropdown list or in a case. So if you make an account for the president of Pepsi in your FogBugz database, this name won't show up in dropdown lists when a Coca Cola client logs on, leading to suspicion, recriminations, lawsuits, and eventually a trip to Camp Cupcake.
But... and this is an important but... if you set up any clients which are visible to all users, this protection is lost. For example, if Beverage Gurus has a fourth client, the local Petting Zoo, and thinks that, heck, the Petting Zoo doesn't have anything confidential, we might as well let everyone in there, they run the risk that a Coke executive and a Pepsi executive will run into each other's names in the user dropdown list, since they share access to the Petting Zoo, and flip out. In summary, if you need to isolate users from one another, you can't have any clients that everyone can access.
Example Two: A Large Company
In a very large company with lots of departments or teams, where each department may work on several projects, it's helpful to divide up the projects according to department, even when there's no security reason to do so. This makes it easy to run filters so that the team management can look at all the cases across an entire department. And if you ever need to set up a secret internal project, you can do so.
Types of Access
When you create a Client or Department, you assign one of the following types of access to each user in FogBugz. This determines, in turn, the access (or lack thereof) that the given user will have to all Projects assigned to the Client or Department you are creating.
- None - The user does not have permission to see or modify cases, or to create new cases.
- Read - The user can read cases, but can't modify them in any way, and can't create new cases.
- Modify - The user can create, read, and modify cases.
When you are editing a client or department in FogBugz, you have three choices:
-
You can give everyone access to the client or department. This is the default.
-
You can give everyone Read access to the client or department, and customize who has Modify access.
-
You can customize access on a per-user basis, deciding individually whether each user has None, Read, or Modify access.
If you choose option #1 or #2 for any client or department, you will not be able to completely, hermetically segregate groups of users from each other, because they can meet each other in that client or department.
Anyone who is configured as a FogBugz administrator will always have permission to read, write, and modify any case, anywhere.
Note that if all you want is for people to be able to submit cases, and be able to view the current status of only the cases they have submitted, this can be achieved by having them send an email to a FogBugz mailbox, or submit to a Project that you have marked as allowing public submissions.
Setting Up Permissions
Setting up permissions is done in four steps:
- On the Site screen, set the Log On Method to "Type email address and password."
- Create the appropriate clients or departments.
- Edit the clients or departments to assign user permissions appropriately.
- Assign each project to the appropriate client or department.
To search for a particular case:
- If you know the case number, enter it in the search box at the top-right of every screen.
- Otherwise, enter your search terms in the box.
- For more search options, just click the "search" button in the top-right corner for a search form.
To search for all cases matching a particular pattern (for example, "all open bugs assigned to Joe Tester,") you need to set up a filter.
If you are using Firefox, you can integrate FogBugz search right into your browser.
Note on Full-Text Search
To implement full-text search, FogBugz relies on the underlying database. If you are using Microsoft Access (Jet) as the database, FogBugz will only be able to search the text of the title of the case.
The syntax of the search phrase depends on the database you are using. To learn about the syntax you can use for searching, simply click Search and FogBugz will show you instructions that are correct for your database.
Every case in the system is given a priority from 1 to 7, where 1 is the highest priority.
You can rename the text labels given to priority 1 through 7 to suit your preferences.
To change the labels:
The best way to use priorities is to have a single, global priority scheme across all your projects, bugs, and features, so that every team member can always work down their list of cases in order of priority.
Here is a typical scheme you might use:
- Life or death emergency... the roof is actually on fire. Drop everything and fix.
- A customer is waiting for this
- Very important
- Important
- Not so important - fix if time
- Probably won't fix but worth remembering
- Do not fix
Each project in FogBugz can have a list of releases.
For example, each major version of your software is a release, whatever numbering scheme you use: 1.0, 2.0,etc. (Or, if you're insane, you can use a simple and obvious numbering system like 1.0, 2.0, 286, 386, 3.0, 3.1, 3.11, 95, 98, 98SE, Me, XP).
Minor versions will also have releases. For example, a typical software project might have milestones of Alpha, Beta 1, Beta 2, Release Candidate, Gold Release, Service Pack 1, etc:
Each milestone has a date; for example, the 2.0 Beta release might be planned for 2/28/2005. You can move the date at will (although your management may be less flexible than FogBugz about changing dates!)
You can set up the list of releases by editing the project. Once you've set up releases for a project, every case in that project can be assigned to a particular release for which you plan to fix this bug or implement this feature. This is sometimes called the "Fix For" of the case.
When a certain release is coming up, you can create a filter to see all the features and bugs that need to be fixed for that release.
When you fix a bug or implement a new feature, before you resolve the case, double check that the Fix For is correct; that way it can also be used as an historical record of which bugs were fixed in which release, and which new features were implemented for which release.
FogBugz also lets you maintain and create Release Notes automatically. See Release Notes.
You can also create meaningful releases without dates, for example, "When Pigs Fly" or "Undecided" or "ASAP".
Although releases are normally per-project, you can also create releases that are usable with any project. When you do this, cases in any project can be assigned to that release. For example, some development teams may rerelease all their software every month. FogBugz ships with "Undecided" as a useful default release. You can also use global releases when there is an event coming up by which time certain bugs need to be fixed in a bunch of projects. To edit these global releases, go into any project.
After a release has already shipped, it doesn't make any sense to assign new cases to it. You should set the "Assignable" field of the release to "No" to prevent new cases being assigned to a release that has already shipped, which also makes the "Fix For" dropdown shorter so it's easier to enter new bugs.
Setting up Projects
Each installation of FogBugz can be used to keep track of multiple projects. On typical software teams, you will set up a project for every individual product that you develop.
Within each project, you can divide cases into areas. For example, you might have separate areas for the Code and the Documentation of your project.
Any administrator can create and edit projects and areas by clicking on the Projects link in the top menu bar.
Each project has a primary contact. The primary contact is the person whom you've designated to look at cases and assign them to the appropriate person to fix. When someone enters a new case, they usually leave it assigned to the primary contact, the default. (In FogBugz every case is always assigned to one person, so that no case can fall through the cracks.)
If you are working on a large project team, you may want to have several people who help categorize new cases. To do this, we suggest that you set up a virtual user account called "Up For Grabs" and make Up For Grabs the owner of the project. You can use as many email addresses as you want for Up For Grabs, separated by commas, so that a group of people receive an email notification whenever there's a new bug in a particular project. Anyone who wants to help sort through new bugs can create a saved filter on "all cases assigned to Up For Grabs" which they check occasionally (or you can create this filter as a shared filter so that all users can see it).
Choosing Good Areas
In general you'll find that the fewer areas you have, the more likely people are to categorize cases correctly into the right area. Think of it this way: if you have 100 areas, everybody who enters a case is going to have to consider each of those 100 areas to decide which area is the best fit. Inevitably, cases will be miscategorized, and the pain of choosing an area may even make people enter fewer cases. If it's easier to jot down a case than enter it into FogBugz, you're going to lose the benefit of bug tracking.
The recommended approach is to start with just one area, called Miscellaneous, and use it for everything.
Then add areas only after careful consideration and only if they are needed for a particular filter that you want to create. For example, if you have a team of technical writers and they want to be able to see all the bugs in the documentation, create an area called Documentation. Don't create more areas than you need for filters, because the more you have, the more likely cases will be misfiled.
Public Projects
You can set a project to allow public submissions. Then someone who does not have a license, but can reach your FogBugz server, can come along, not log in, and click Enter a New Case. This is what they'll see:
After submitting this case they are given a link that lets them view the current status of the case:
They can bookmark that link and come back at any time to view the status of that case. They will not see the comments that licensed users enter, only the status of the case.
When viewing the status of a particular case, they will be provided with links to view the statuses of all the other cases they've submitted.
If someone sends an email to a FogBugz mailbox, you can set it so that they will be sent a ticket number for their new case. They can then click "Check the status of a case" on the main FogBugz page and enter their ticket number. A ticket number contains random letters, so that people cannot guess other people's ticket numbers, and it allows the submitter to see all cases ever entered using their email address.
When you release that great new version of your software, your customers are going to want to know what's fixed and what new features you're giving them. FogBugz makes it easy to maintain release notes as you go along, effectively attaching a release note to any case.
- Note that you will almost certainly not want to add release notes to every case. Some are too trivial for customers to care about. Others might reflect bugs that were introduced during development and fixed before any customer had a chance to see them, so customers will have no reason to care.
- FogBugz does not attempt to compose release notes automatically based on the bug report, because bug reports are not usually worded the way you want your release notes to be worded: they include insider jargon, abbreviations, etc. Instead FogBugz requires you to create a release note for each bug in your own words.
Once a case is resolved, you can add a release note to it simply by clicking on the link marked Edit Release Notes next to the status of the bug and type in or edit a release note.
To see all the release notes for a particular release (a.k.a "fix for"), go to the main menu of FogBugz by clicking on the FogBugz icon in the top left corner, and choose Release Notes. Choose the release you are working on, and you will see a list of cases that were resolved for that release. From here you can go to any of those cases to write or edit any release note.
At the bottom of this screen, there are two small icons, one marked HTML and one marked XML.
The HTML icon displays all the release notes on one page. It uses extremely clean HTML with all formatting done in a style sheet. You can use your favorite HTML editor to format the release notes any way you like. By editing the styles you can control the formatting of the entire release notes document to match your exact requirements. Here's one example of this output.
The XML icon displays the same thing in XML format, suitable for any further processing you may need to do to integrate the release notes with your web site or documentation or any other electronic interchange or content management system.
The Site screen on the Administrator's toolbar is used to configure installation options for FogBugz.
To learn more about custom settings, read these topics:
When someone reports a bug, it is helpful to report what version of the software they saw the bug in. This might be a shipping version (e.g "2.0 with service pack 2") or it may be a development version ("the build that Harry gave me on 9/5/06").
Every case in FogBugz has a field called Version, which can be used to track this.
There are probably a lot more versions than releases; many programming shops have builds every day and it is helpful in reporting a bug to indicate exactly which build it was found in. That's why the Versions field is just free-form text.
When you enter a new case the default version will be the same as the last case you entered; this way if you are testing a particular version of code and you find lots of bugs you don't have to keep re-entering the version.
- Note: The "versions" field is hidden by default, to simplify bug entry. To un-hide it, log on as an administrator and go to the Site Screen and modify the "Extra Fields".
To help make estimates of when the project will be complete, FogBugz lets you enter an estimate for any case. An estimate is given in days and/or hours. You type it in using the form 1d4h, for example, which means 1 day 4 hours. You don't have to include both parts: 8h is considered equivalent to 1d; 12h is the same as 1.5d or 1d4h.
Note: if your days are not usually 8 hours long, an Administrator can change the length of the day. Click Site and then click on the link to configure the working schedule. For example, if your company is particularly bureaucratic and programmers spend half of their time in meetings, you can configure FogBugz to use 4 hour days, so a "3 day feature" is the same as a "12 hour feature".
You can use 0.25h for a quick, fifteen minute case. The only thing you can't enter is 0, because that is indistinguishible from "no estimate at all."
Using filters, it is easy to search for all the bugs without estimates so you can add estimates.
If you ever change an estimate, the original estimate is remembered next to the current estimate. That is useful if you want to go back to your old bugs and see how good a job you've done estimating in the past, so you can learn to estimate better in the future.
Once you enter a non-zero estimate, you can enter the elapsed time, and FogBugz will automatically calculate the remaining time. For long features which take several days, at the end of every day's work, you can re-enter your current best-guess estimate and the amount of time spent so far.
For an interesting article about successful software schedules, read Painless Software Schedules by FogBugz designer Joel Spolsky.
At the bottom of any list of bugs, FogBugz will always calculate a summary of the estimated time for all bugs shown in that particular list. If you are careful to maintain estimates and elapsed time as you go along, you can use these summaries to get a good approximation of how much work is left in a release.
Optionally, any case can be given a due date and time. This is as easy as clicking on the calendar and choosing a date and time:
To make it even easier to set due dates, you can simply type certain English phrases in the due date box. When you leave the due date box, FogBugz then tries to interpret what you typed. All of the following examples will be interpreted as expected:
today
tomorrow
the day after tomorrow
in 3 days
in 1 week
tuesday
next friday
march 1
12/30 (or 30.12 outside the USA)
12/30/2006 (or 30.12.2006 outside the USA)
june
In the "time" field you can either enter a time, or type things like:
noon
midnight
now
in 1 hour
in 3 hours
Once you've entered due dates, you can:
-
filter and sort to find cases that are overdue or bugs that will become due in a certain amount of time
-
subscribe to a daily email report sent out every morning listing all past-due cases and all cases which will become due that day. You can subscribe or unsubscribe in the Options screen.
You can set up FogBugz so that incoming email is automatically given a due date, for example, to insure that customers receive a response within one business day. Learn more.
What's an Administrator?
Any FogBugz user can be made into an administrator. You can have as many administrators as you want.
Administrators have the ability to:
- Configure and add users, and change their passwords
- Set up projects, areas, shared filters, clients, and departments
- Configure all aspects of the FogBugz installation
- Install new licenses purchased from Fog Creek
Also, all administrators receive a copy of the email that is sent when users choose Email Your FogBugz Administrators option on the Help menu.
No matter how many FogBugz licenses you have, FogBugz will always let you create one extra user that can be used as an administrator's account. For example, if you purchase licenses for 10 users, you can actually create 11 users. This free admin account is built in; it cannot be deleted, but it can be renamed and transferred to another person.
Importing From Bugzilla
We offer a script for importing bugs from Bugzilla into FogBugz. This file is called importBugzilla.asp on Windows systems and importBugzilla.php on Unix and Mac systems. To get started, bring it up in your browser like this:
Windows: http://YOUR-FOGBUGZ-SERVER/importBugzilla.asp
Unix: http://YOUR-FOGBUGZ-SERVER/importBugzilla.php
Mac: http://YOUR-FOGBUGZ-SERVER/importBugzilla.php
All Other Tools
For those of you looking to import from something other than Bugzilla: The wide variety of database formats in use for the wide variety of bug trackers in existence makes it hard to devise an import feature that could handle all of them. So, to import your data, you would need to use a database tool. The FogBugz database is pretty straightforward with mostly self-explanatory names, so figuring out a one-to-one mapping of the fields from your existing database to ours should not be too hard. We do offer a 90 day no questions asked money back guarantee, so you could try it and if it just isn't working out we will refund your purchase.
If you're using SQL Server, DTS (Data Transformation Services) provides a very intuitive interface for doing this. MS Access has import tools as well. If you're using MySQL, click here for a list of conversion utilities.
For troubleshooting guides please see our online Knowledge Base. We keep the online support pages up-to-date as new issues pop up.
Who and What is "The FogBugz User"?
The FogBugz web application uses one specific Windows user account to take actions via IIS. This account is commonly referred to in short as "the FogBugz user".
Note: If you need to switch this user, or change it's password, you need to know that this user needs the following permissions on the web server:
- Full permissions on the FogBugz folder (and all child objects), normally located here:
C:\Program Files\FogBugz\
- Full permissions on the FogBugz registry key (and all child objects) located here:
HKEY_LOCAL_MACHINE\SOFTWARE\Fog Creek Software\FogBugz\
- You may also be using the FogBugz user in your database connection string.
To determine what Windows account FogBugz is running as within your IIS follow these steps:
- Open IIS (Start > Programs > Administrative Tools > Internet Information Services)
- Right click on your FogBugz directory in IIS and get properties.
If you installed it in your root directory, right click on Default Web Site.
If you installed it as a new virtual directory, right click on that virtual directory.
- In the properties dialogue, go to the Directory Security tab and click Edit for Anonymous Access:
- In older versions of Windows (Windows 2000 screenshot shown below) click Edit for the "Account user for anonymous access". Note that "Anonymous access" should be checked and "Integrated Windows authentication" should not.
- Make note of the "User name".
Note: If you do not see Administrative Tools in your Windows Start Menu:
- Right click on the Windows Taskbar and choose Properties.
- Go to the Start Menu tab and click Customize.
- Make sure Display Administrative Tools is checked.
Google, Yahoo, Amazon, etc all come as default searches in Mozilla Firefox.
In a few easy steps, you can integrate Firefox with FogBugz to make searching your FogBugz installation as simple as searching Google.
- Download fogbugz.src and fogbugz.png
- Edit fogbugz.src with a text editor and replace the urls to point to your FogBugz install.
- Move fogbugz.src and fogbugz.png to your Mozilla searchplugins folder and restart Firefox
Linux: /usr/lib/Mozilla/searchplugins
Windows: C:\Program Files\Mozilla Firefox\searchplugins
Mac: /Applications/Mozilla.app/Contents/MacOS/Search\ Plugins
- Now you can type either a bug number or a search term in the Firefox dropdown and you are all set.
- To learn more about search plugins for Firefox, visit http://mycroft.mozdev.org/
- Future versions of FogBugz will allow you to single click install this from the Options page.
HTTP compression can drastically improve FogBugz performance by reducing the amount of bandwidth consumed for each page load. Enabling HTTP compression is easy for both IIS and Apache, and you'll find that your FogBugz pages are reduced to approximately 10% of their original size. You will pay a slight penalty in increased server CPU load, but we think that the tradeoff makes HTTP compression a no-brainer.
IIS 5
Download the free tool available at http://sourceforge.net/projects/flatcompression (follow the links to download FlatCompression...you want to download FlatComp-R-1.20.226.dll.zip). FlatCompression's extended documentation is available, but you should only need to follow the simple steps below.
- Unzip FlatComp-R-1.20.226.dll and place it in C:\Windows\system32\inetsrv
- Go to Control Panel | Administrative Tools | Internet Information Services
- Expand "Local Computer", right-click on "Web Sites", and click Properties
- Click the "ISAPI Filters" tab, click Add, and enter "FlatCompression" as the filter name.
- Browse to C:\Windows\system32\inetsrv\FlatComp-R-1.20.226.dll for the executable.
- Click Ok, restart IIS.
IIS 6
IIS 6 ships w/ support for HTTP compression, but you need to take a couple configuration steps. Scott Forsyth's walkthrough is the best detailed explanation we've found. Follow his three simple sections (Enable Compression in IIS, Create a Web Service Extension, and Now for the metabase changes), and you should be all set.
Apache
If your PHP is built with zlib, then adding compression should be as simple as adding the following line to your php.ini, and restarting apache:
zlib.output_compression = On
There are a couple of caveats; for instance, this won't work with ob_gzhandler. For a fuller explanation, check out http://php.net/zlib. If you're not sure whether or not your PHP is built with zlib, you can create a test script as shown here: http://www.fogcreek.com/FogBugz/KB/trouble/fogutil.soProblems.html, and look in the "Configure Command" section.
That's it! Your compression should be up and running, and if you keep an eye on your network traffic you'll notice that individual requests consume significantly less bandwidth.
Before starting, check that your system meets the minimum system requirements:
FogBugz for Windows System Requirements
Then run FogBugz Setup, which is mostly self-explanatory:
Running FogBugz for Windows Setup
If you have any trouble or need to customize the FogBugz setup, we have a detailed description of exactly what setup does, for advanced system administrators:
What Setup Does
For further help please contact Fog Creek Software. Our programmers will be happy to help you and we even have the ability to remote control your server using VNC techology and get FogBugz installed for you.
FogBugz Online Support
Before installing FogBugz for Windows, you should run through this checklist to make sure your server has all the required components.
Computer
Any Pentium-class computer will probably be fine for most teams. We've run databases with over 100 users off of a single Pentium II/266 MHz. We recommend at least 512 MB of memory for optimal performance.
Operating System
FogBugz for Windows works on the following operating systems:
Windows 2000
Windows XP Professional
Windows Server 2003
Windows NT 4.0 No Longer Supported
We no longer support Windows NT 4.0. FogBugz 4.x and above have not been tested with Windows NT 4.0.
Windows 2000
FogBugz is compatible with Windows 2000 Professional,
