Capture Mozilla/Bugzilla/Bugzilla For Humans Transcript
Welcome to Bugzilla for Humans.
We're going to take about the next 15 minutes and walk through the basics of navigating Bugzilla. I'm assuming that you don't have very much background here but, even so, I'm going to blow through things a little bit quickly, so... It's a video; if you need to, feel free to watch it more than once.
First things first. My name's Johnathan Nightingale. I'm johnath in Bugzilla, on IRC, and email and basically everywhere else. This is me... oh, actually, this is me. I'll be your tour guide.
So you want to use Bugzilla? That is a lie; nobody wants to use Bugzilla.
<view of bug>
It's very complicated and daunting and seems filled with information that no human is meant to understand.
<view of evil comment>
It's also full of very terrible human beings.
But it turns out that Bugzilla is also one of the strongest tools we have. It scales to hundreds of thousands of bugs. We tried other bug trackers but we haven't seen a lot that can stand up to the load we put on it. It can be moulded to suit a variety of purposes; it's open source, we have people in the community who understand how to manipulate it, and it's the devil we know. Moving to something else right now would be really hard; we've learned how to work with it, and the point of this video is to help you work with it too.
And at the end of the day, once you come to understand it, you can make vague movie references that may or may not be hip by the time your viewers are watching this.
Let's get started.
So the first thing you need to do is create an account. The good news is that this part is really easy.
<view of front page>
Just go to the main page of Bugzilla, it may or may not look like this by the time you get there, click on the Open A New Account button. The only piece of information it wants from you is an email address. And then you'll go through the standard "click here to verify your email address", and you're off to the races. At which point you'll start getting bugmail. And you will be sad. But I'll talk to that later.
Review: it's scary, but it's important, and getting started is really easy. I hope you are still with me.
Alright. Filing a bug.
<view of pretty product chooser>
The first time you try and file a bug you'll see a screen that looks like this, and tries to sort of steer you so you can figure out where this bug needs to be filed. As you get more advanced, you'll turn off this screen and go to the screen that lists all the products,
<view of main product chooser>
and you'll once again feel that sense of terror deep in your gut because there's just simply too much here to process.
<view of simpler bug filing form>
Then of course when it comes to filing a bug, this is the basic form. This is the form where we think we're only showing you the easy stuff, and then when you click that "Show Advanced Fields" button at the top,
<view of full bug filing form>
it turns to this. Look at that - you can't even see the Description box within this first page of fields. Don't worry too much about it. We'll get through this together. Remember, the point of filing a bug is to get it resolved, right? Let that be your guide. You are not filing this bug to do a bunch of paperwork, you are filing this bug to report a problem, to make a piece of software better, or to make a request that somebody else can fulfil for you. So don't get daunted in the details.
<Slide: That means: * CC list matters * Component choice matters * Summary matters * Helpfulness matters>
Here are the things to keep in mind. Your CC list matters. So, every bug - you can attach other people to it, you can carbon copy them. And all that means is that they'll start getting email when the bug changes, just like you are. Managing that CC list, especially in the early days, is super-important because if you CC the right people onto the bug, it doesn't actually matter too much where it lands. They've got more context rattling around in their brain than you, they've gone through this process before. CC your manager if you are not sure, CC people that you know work in that general area. If those people see the bug, they'll move it to where it needs to go, so that you don't have to fight so much with the next important thing, which is figuring out where to put it.
Everything in Bugzilla lives in a Product and a Component. So the Products are very high-level things like Firefox and Thunderbird, and the Components are pieces of that. So inside of Firefox there's a Menus component. The problem is, sometimes it's hard to know. If you see a problem with Firefox, you might want to file it in the Firefox component, but if the problem is that a web page isn't rendering properly, well that might actually be in the Core component, where we put all of the guts of Gecko, the engine that underlies Firefox. So this is a bit of a learned skill. But again, if your CC list is strong, people can help you out. Make your best guess. I know people who have been with the project for 10 years still have problems choosing the right component.
Your summary matters a lot. If you describe the bug well, if that first line articulates the problem you are having, people are much more ready to engage and think about where within their purview that problem might lie, and start to freewheel on what the answers might be, and what the bug might look like. Put some thought into it. If you are filing a bug to get your blog added to Planet Mozilla, don't have a summary that says "Add my blog to Planet Mozilla". That's what every bug summary looks like. Say "Add Johnathan Nightingale's blog to Planet Mozilla". At least that gives us some way of distinguishing; people understand what's different between your bug and the 700 other bugs that have been filed that look very similar. Remember that your job here is to get the problem solved, and that means helping the people who are going to solve it.
And that's what the last bullet comes down to. Helpfulness matters. You know? Lay it out, help them help you.
<slide of unhelpful bug summaries>
This is what not to do.
Reading a bug. So, filing a bug is some amount of complexity.
<slide of a bug>
Reading a bug is even harder - look at all this! There's tons of stuff here and it can be very hard, when you load a bug, when somebody says to you, whether you are in engineering or not, you know, can you go take a look at this bug? This is the first thing you are going to see, and you are just going to fall over dead. But the good news is that you can ignore most of this. It's here for bookkeeping, it's here for the experts, but for you when you are just getting started -
<highlight summary area>
look at that. Alright? You've got the bug number, you've got the summary. Now you see why the summary is so important. We put it in bold, we put it at the top of the bug list. So make sure that that is well descriptive. The status of the bug - is it new? Has it been assigned to someone working on it? Has it been already resolved, and you are evaluating whether to reopen it? Who reported it and when it was last modified are sort of a good sort of sense of, I don't know, the quality of the bug, the activity of the bug. And then the whiteboard and keywords - these are going to feel in the early days like they are interchangeable, and to a large extent they are. The only difference is that the keywords are sort of structured - we create new keywords, that's an explicit choice we make, and so there's one called regression. When you add those keywords they show up in all kinds of people's custom searches. Whiteboard's a little more fluid. You put something in the whiteboard - it can be text, it can be a de-facto keyword that we just haven't bothered to create as a keyword yet - but if you look at these six pieces of information right here, you've got a good sense of what the bug's about, and how the bug is behaving right now.
<slide of patch history>
If you scroll down the page a little bit the next thing you see is the patch history. If you are an engineer this is more relevant than if you aren't, but basically this is a history of every patch that's been attached. Review and super-review and branch approval and things like that, we are just not going to talk about today. So, if you are an engineer, that'll be for next time, and if you are not an engineer, just pretend you didn't listen to the last 28 seconds.
<slide of comments section>
Comments. This is where the actual activity of the bug is, and it's everything below that sort of bookkeeping metadata. Mostly these just look like comments, you know? There's a bunch of stuff hanging around the edges, but if you just look at these as comments, it's a nice chronological history of the activity in the bug. And usually if someone says to you "can you go take a look at that bug and tell me what you think we should do", this is where you are going to spend most of your time - understanding the context that other people have created before you. I do want to call out a couple of little pieces though, because they are handy. Obviously every comment is marked with who made it and when they did, but they are also numbered. And those numbers are links. And so if you want to direct someone in IRC or in IM or in an email or whatever, and you want to say "go check out that crazy thing that David Bolter said", you can just right-click on "Comment 22", and copy the link, and paste that, and it'll jump right to that spot for anyone who clicks the link. So that's a little bit handy.
You can click "Reply" if you want to reply to someone. You can see that David's replied to someone here; the quoted text is in purple and then his text is there in black. The last thing I wanted to mention here is that you'll notice Bugzilla tries to be a little bit smart. If it sees you say "bug 513715", if figures out that you are probably referring to other bugs in our bug-tracking system and so it links that. And in this case it has crossed it out because that bug's already been resolved. But really, don't worry if stuff is already starting to leak out of your brain. The point is, this is where the discussion happens, Bugzilla tries to be smart and helpful, you'll learn to use these tools as they become necessary.
Review. Bugzilla is scary, but it's important, and getting started is really easy. I hope you are still with me on that one. Filing bugs is about helping people help you. Alright? That's really important. Just keep that at the forefront of your brain for the first 50 bugs you file, and you will be a ninja in no time. And reading bugs is about learning what to ignore. And as for what you should ignore - you should ignore most of it.
<slide: Finding Bugs>
Finding Bugs. OK, now we're getting into more exciting stuff. There are 2 or 3 different search interfaces in Bugzilla, because of course there would be. One is complete, and terrible.
<slide of main query interface>
It looks like this. Unless you specify every field and every parameter, and there are boolean charts down off the screen which you can't even see, like... If you need to be able to specify with this level of precision exactly the bug you want to find, this is the tool for you. It's just terribly complicated and for 99% of searches you don't need it.
The other way we have for searching Bugzilla is beautiful, but as I say it only works 99% of the time. It looks like this
<slide of Quick Search box>
Look at that. It's lovely. It's so diminuitive, it's so efficient. You search for words by typing in the words, and it will search in all the places it should search. It'll search in the Summary, it'll search in the Status Whiteboard, it'll search Keywords and things like that. If you want to constrain a search, or if you want to search for some field that isn't included by default like the Product name, just put a keyword in front of it. Product colon Firefox. Reporter colon Johnath. Real Player. Like that's going to find me all the bugs in the Firefox product that Johnath reported. It makes me weep.
<slide of keyword error>
And if you're not sure what the keywords are just guess! Most of them are the natural thing - Reporter is 'reporter', Assignee is 'assignee'. But if you guess wrong, that's OK, because the result page you are going to get back is going to tell you "I don't know what that keyword is, and here's a list of all of them". So you can just get that cheat sheet any time you need it, but most of the time, these searches will just fly off. It's really worth spending some time getting used to QuickSearch.
More Review! It's scary, but it's important, and getting started is really easy. Filing bugs - make them helpful. Learn to ignore what you don't need, and learn to love QuickSearch. Everyone still with me? We're half way done.
Pro Tips. Alright. First Pro Tip is etiquette.
<slide: etiquette URL>
Here's a URL that you can't click on because this is a video. But what that URL says is to remember that you represent the community. OK? Bugzilla is full of human beings and, believe it or not, most of them are there because they are trying to be helpful. Even the ones that aren't actually being helpful are mostly there because they are passionate. Sometimes we get trolls, but mostly even the people who are swearing are swearing because they are frustrated about a product that they really love. And remembering that will make you a better human being (probably) and certainly a better ambassador of the community.
That means you don't have to win. Right? If people come in throwing temper tantrums, you've got all the context, you've got all the background, and you've got all the friends in the Mozilla project. So it's easy for you to just tear a strip off them. But remember that, at the end of the day, our purpose here is to make an awesome product, an awesome family of products to make the Internet better. So if there's usefulness in their complaints, in their comments, try and lead them towards being productive instead of just beating them up.
But you also don't have to lose. Right? We don't run this project democratically, we don't take votes, and we certainly don't have to humour everyone who comes through the door having a temper tantrum. Somebody's doing that on your block, and you don't think that their usefulness outweighs their pain, feel no obligation imposed by me to treat them with anything other than dismissal. You are a human being too.
Next Pro Tip. Finding bugmail addresses.
<slide of match screen>
So this comes up a lot. You'll want to take my earlier advice, and add somebody to a CC list, or maybe you are actually going to assign a bug to someone, so you type in part of their name (you don't know their whole name, you don't know which email address they used for Bugzilla) and what you end up seeing is a page that looks like this which says "oh, look, the string you gave me is not unique", and it gives you a very long picker, and even still that may not have all of them if you pick something really generic like "John", there are going to be enough of those in Bugzilla that it's only going to show you the first 50,000 or something, and after that you are just going to have to constrain the search more.
<slide of CC add picker>
One thing to remember is that substrings work. So you don't have to give full addresses; you can say something like "gavin.sharp" and that will match all the gavin dot sharps but conveniently enough, right now, there's only one of those. And you don't even need all of gavin.sharp. If you want to add him to a bug, "vin.sh" is actually a substring which turns out to be unique. That's stupid, and there's no reason you should have to memorise that, but because it's a system that works, and because it's a problem we all have to solve, we all do this stupid thing.
<slide of comments with colon prefix tags highlighted>
So when you're reading a bug you'll see this. Everyone's name is beside their comment, but after their name, they've got this cryptic little nickname, often in square brackets, often preceded by a colon. Why do they do that? They do it because that system basically always gets you what you need to get. If you need to copy vlad on something, you don't need to remember that he's vladimir@pobox, you can just do colon-vlad. Probably he's the only one who's done that, because it's not typically part of an email address. So it's probably just something he's done very deliberately. This works really well when you know people from IRC, but you don't know their bugmail name. Just : and then their IRC nick, probably that gets them. You can do that yourself by just going into your Bugzilla preferences, where it asks for your full name, and instead of saying that your full name is Awesome McAwesome, you will say your name is Awesome McAwesome square bracket colon awesome. To belabour the point.
<slide: Bugzilla Pro Tip: Watching>
Next Pro Tip: Watching. This one's kind of creepy. If you go into your Bugzilla email preferences, you can actually watch other people. So this can be really helpful when you are getting started. If you are new and you're, let's say, in an engineering group, and there are other people working on the same stuff you are, maybe you just want to add their bugmail addresses to your watchlist. And any time they get bug mail for any of the thousands of bugs they are working on, copied on, otherwise involved with, you'll get an email too. And it's a firehose, I mean really, it's a lot to take in, but it'll help you see the flow of the stuff that you care about. Creepy but useful.
In fact, you can do a step more.
<slide: bug with QA contact highlighted>
In addition to following individuals, you can sort of follow components, thought this back door. Right? So, on any page, for any bug that you look at anywhere in the projects that you typically work on, there's a QA contact. And you notice the email address there is pretend - menus at firefox dot bugs is not a real email address. But every component in Bugzilla has one of these QA contacts, and at least within the Firefox and Gecko projects, we don't screw with them. We don't actually use them to represent the person in QA that you should contact. That's a very broken behaviour of ours, but it has this nice side effect. Because we never change that, if you stalk this pretend user, if you add firstname.lastname@example.org to your watch list, you'll start getting bugs, or bugmail, for everything in that component. Right? Because the QA Contact is added by default, it's on every bug in that component, and so if you are watching that fictional human being you are getting all the email that they would be. So if you are in charge of a particular component, whether it's a technical component or not, doing this can let you stay on top of new bugs as they are reported instead of having to watch for that very manually.
Which brings me to maybe the most important Pro Tip: managing your bugmail. So, by default Bugzilla assumes you want to know everything about every bug that you are in any way related to. You do not.
<slide: screenshot of user email preferences>
If you go back into your User Preferences, there is a tab called Email Preferences, and if you look at it you'll see there is this very daunting table, because clearly as you've learned by this point, Bugzilla is the land of very daunting tables.
Nevertheless, what this does if you take a second to understand it is say "OK, based on my relationship to the bug, here's when I want to get email about it." So when you're assigned to a bug, you basically, you probably want to know everything that happens to that bug. I certainly want to know if it's resolved or open. I certainly want to know if the priority has changed, or if new comments have been added or if new attachments have been added. But as you distance yourself more from direct interaction with the bug, once you get to the point where you are just CCed on the bug, you don't need as many of those status emails. Mostly, if you are CCed on a bug, you want to watch it unfold, and you want to see when it's resolved. You don't care too much if the status of it changed, or if the target milestone changed, you really want to see "how is my bug progressing?"
At the start, if you just want to get a feel for it, leave everything on default, and be buried in it for a couple of days, but you'll come running to this pain [sic] pretty soon, because it's how you reduce your bugmail to a sane level.
This is it, this is the final review slide, folks. Bugzilla is scary, but it's important. If you are anywhere near Mozilla it's the lingua franca, it's the thing you need to know. When you are filing bugs, help me help you, and when you are reading bugs, learn to ignore what you don't need. Learn your quicksearch, manage your bugmail, and be nice. Now go set up your account.