Category: KDE

This is the fifth post in my blog series: bugs.kde.org for developers.

Our bugtracker supports three version information for each bug report:

• The version against which the bug got reported
• The version when the bug is going to be fixed
• The version when the bug got fixed

All of these are very important information in the bug fixing workflow. The better these version information are set, the more information you have for searching bugs, but also for changelog and feature plan information.

Version

The version a bug got reported in is probably the most important information of all version information. It should be set by the user who opens the report and it contains very valuable information. E.g. if a user reported an issue you know it is fixed you don’t have to start to panic that the fix is incorrect if the user set the version field to a completely outdated one. Point the user to the new version and set it to duplicate or fixed.

Also if a user sets the version to your latest release it’s very easy to spot that there is a regression. But most important DrKonqui can automatically set the version when uploading a crash report to bko. This is an automatic generated information and you know it is correct and not some maybe wrongly entered information by the user.

Now the bad news: you have to maintain the versions. Nobody is going to add the versions for you. It is your responsibility to add the version. To manage the versions you need the editcomponents privileges or have to enter sysadmin requests. As a new version is required each month, you probably want to go for editcomponents privileges.

But it’s not much work. It requires once a month to add one more version – that’s it. At the same time you can also disable old versions. This means users can no longer report bugs against this version, but the version itself and all its information stays in the bugtracker. For KWin we currently only have two versions for the latest two releases open: 4.7.4, 4.7.5, 4.8.1 and 4.8.2. We are no longer interested in any bugs for 4.6 or older as well we are not interested in any minor releases which are not the latest ones. This is a very important feature of bugzilla as it tells the user when reporting the bug that there is a newer version available and that the user should first try to update the version. Nothing is more annoying then getting bug reports for bugs fixed in 4.7.4 and users keeping reporting it for 4.7.1 because $DISTRIBUTION does not ship updates.

Most products have a version to represent the current development version, e.g. “git master”. Please be careful with such version information. Think about what “git master” means in half a year or a year from now? Do you still remember what version it was or has maybe someone updated the bug because it has still been present in current development branch? It is probably better to have correct version information. That is if you report an issue running master and you know it has already been present in the latest stable, set the version information to latest stable. And during the beta phase it makes sense to add version for each beta version and update all existing “git master” branches to the first beta version. For beta versions it also makes sense to disable the versions as soon as the next beta version becomes available – you don’t care about it any more.

Version Fixed in

The opposite of the version which has a bug is the version which fixes a bug. Bko has a custom field for this information called “Version Fixed In”. This is a free text field, which means that it does not have a controlled vocabulary like the version field.

This field gets filled in automatically with your git commits. Just add a

BUG: 12345
FIXED-IN: 4.8.3

to your git commit message and on push the commit hook will set the bug to RESOLVED FIXED and update the version fixed in field. For a full list of keywords you can add in git commits, please see the documentation on SVN Commit Policy.

The version fixed in is a very important functionality for our users. It tells the users when they can expect the bug to be fixed and users finding the bug report will find it confusing that the bug is RESOLVED FIXED but they are still seeing this bug. Having the fixed in information available helps users understand that it will be fixed with the next version or with the next update.

Also the version fixed in field is used by the ChangelogGenerator to generate the changelog for the next bug fix release. Only bugs which have the fixed in field filled can be considered by the ChangelogGenerator. Of course it is very important to have a good changelog as that shows our users that we really care about them and fixed many bugs. Also it is very important for the distributions to see what got changed in a bug fix release which is important for their communication about updates.

There is no reason to commit to the stable branch without BUG and FIXED-IN keywords. If I had to say anything there would be a git hook to forbid pushes to stable branches without BUG and FIXED-IN fields 😉

Target Milestones

Last but not least we want to have a look at release planning with target milestones. This is again information which you have to put into bko and which is hardly used by any product in bko. I am not aware of any product except KWin making use of target milestones. If your product does please leave a comment – I would be interested to have a look at your workflow.

Target Milestones help you to plan your next bug fix and feature release. You really have a bug you want to have fixed in the next stable version and you want to ensure that you don’t forget about it? Add a target milestone to it. You want to see what will go into your next version? Add a target milestone to it. You want to use bko to help you decide what you have to work on: add a target milestone to your bug reports.

Having your bugs and feature requests annotated with target milestones helps also with the feature plan. The ChangelogGenerator mentioned above is able to generate MediaWiki syntax for our feature plans based on bugs annotated with a target milestone.

Of course target milestone is a feature which should only be used by developers. No user is allowed to do so and if a user ever changes the milestone you have to reset and inform the user about the mistake.

This is the fourth post in my blog series: bugs.kde.org for developers.

Yesterday we looked at how to search in bko if there is useful information in it. Today we start adding the useful information: components. Now again I assume you will say that you know everything about components, but I have assigned bugs to so many products with too few components, that I decided components deserve an own post in this series.

Components can be used to group your bugs. You can use any grouping which might make sense to you. You could add components for the parts exposed to the user interface, components for implemented concepts (e.g. a protocol) or components for specific parts of the code base. My recommendation is to remember that the bugtracker is there to help you and that means you should use what makes sense to you and not what might make sense to users. Please don’t expect that users or triagers will find the right component – setting the component is something the developers have to do.

One of the advantages of components in my opinion that it makes bko less scary. You might have hundreds of bug reports which is difficult to manage and to go through. But when they are nicely separated in components everything is less scary. Your components might just have something between 10 and 20 bugs and that makes everything look much better. Just have a look at the component report of KWin.

The component report for your product is something you should bookmark. It is a very useful tool when searching for duplicates. You know the new reported bug has a duplicate: just go through the few bugs reported to the component. Much faster than using a search query.

If your bugs are nicely triaged into components it becomes much easier to work with the bugs. You can easily see which bugs exists for a specific code area, you immediately find the duplicates and similar bugs and you can nicely plan how to fix those bugs. There are very handy features to help you do the bug fixing planning – but that in a later post. Also you easily spot areas which requires work: if all your crash reports are in one component it might be a good idea to increase the priority of fixing bugs in that component.

In case you have developers in your team responsible for a specific part, you can set the developer as the default assignee and your general team bug account as the default CC list.

What we have not yet discussed is how to create components. There are two possible ways: create a sysadmin request to get the components for your product (sysadmin will need name, description, assignee and cc list) or in case you are a maintainer you could request to get higher privileges to create the components yourself. I highly recommend the latter as that makes your work with bko much more flexible. While doing a triaging session lately I realized that we need two additional components and I could just create them and send the bugs there without waiting for sysadmins to act and they really have enough work to do 🙂

You don’t have to be afraid of components becoming obsolete in future versions of your software: components can be deleted (if there are no bugs assigned to it) and can just be disabled, so that no new bugs can be assigned to that component.

This is the third post in my blog series: bugs.kde.org for developers.

Today’s blog post in my series on bko for developers is about searching in bugzilla. Now you will say searching is easy I know all about it: trust me if you are not a developer of Amarok/Phonon, Plasma, KWin, Solid or Telepathy you will learn new things. Yes bko can even tell me if you know how to search 😉

Searching by bug number

On each page of Bugzilla you have access to the quick or simple search through a very prominent field. This is a great search field for users, but mostly useless for developers: you don’t want to use it. A more detailed explanation can be found in the help on Quicksearch.

Quicksearch is a wonderful tool if you already know the bug number or alias you want to go to. But if you already know the bug number you don’t need to use Quicksearch, but you can use a web shortcut in combination with KRunner:

The web shortcut “bug:” allows to search in bko with search term either bug id or alias independent of used browser. If you don’t know about alias: you can give each bug a human readable name – the alias. That is particular useful if you have a bug report which has many duplicates like the one in the screenshot. To set an alias you need to edit the bug summary which reveals a field to enter the summary. Use the alias wisely: you need to remember it and remember that bko is a global database, so better use a prefix.

The Advanced Search

The real search for developers is the Advanced Search. It has an entry in the global navigation, but I recommend you not to use it, but to set a bookmark on a slightly adjusted link with “&product=“. You will most likely just search in your product and bko hosts many products and especially many which start with a “k” ;-).

Now what is important to know about the Advanced Search is that it is not about searching like e.g. Google. Of course you can also use it to search in bko, but it’s much more powerful. It is the key to turn bko into a tool to support your workflow. In my last post I wrote that I use emails to get all information about bugs for kwin. This is only partially true, I start to transit to using only searches.

Why is the search so powerful? It allows you to search on any information you put into the bug. You want to have all bugs in a specific component reported between beta tagging and beta release? No problem with advanced searches. You want to see all bug reports with a specific target milestone and having a patch as attachment? No problem with advanced searches.

I use the searches for example to see all bugs which have changed for KWin in the last 24 hours. That is very similar to what I also have in my mail inbox. But it’s better: it gives me the context on how I need the bug. What’s the status of the bug? When has it been changed before? Is it scheduled? Confirmed? Triaged? All these information I have in one table, but are missing in the mails. It allows me to better schedule when I want to work with the bugs.

Other searches I use are for bugs with a specific target milestone. It is so to say my personal TODO list. It needs more work, but it can be tuned into telling me what I have to work on today.

So it is a very powerful tool and the UI is very complex, that’s why I cannot introduce all the specific features in this post. I can only suggest to start reading the documentation and experiment with the search capabilities.

Saved Searches

As mentioned the searches are very powerful and that means it takes quite some time to get the query in the way you want to have it. And if you use the same query again and again (e.g. all bugs changed in the last 24h) you don’t want to spend five minutes on setting up the query each time.

Of course bko has something for you: saved searches. Whenever you perform a search, underneath the search result there is an input field to name and remember the search:

As you can see the saved searches are shown in the footer of each page and you can always get to a search by just one click.

Defining searches and saving them is already a quite important feature to efficiently work with bko. But you normally work in a team and you can expect that your team mates have to search for the same things as you do, right? It would be a pity if everybody has to setup the searches. Of course bko has a solution for this problem. Go to Preferences -> Saved Searches. Here you can edit and manage all your searches but even more important you can share your search with groups.

If a search is shared it is listed on this page and you can just add it to your searches shown in the footer. So all the searches defined by your team members can be made available for the complete team. As shown in the introduction only very few teams make use of this feature, in fact it looks like half of all saved searches are for Amarok/Phonon. And Amarok is one of the products which got the bug count quite low over the last few years. So learning from the great work done there will help you.

Going Through Search Results

When working with the searches it’s of course important to see the information you really need. Therefore the search layout can be customized using “Change Columns”. This allows you to add/remove and reorder the columns listed in the search. Of course you can save the layout for each of your searches or just change the layout for your current session.

If you use the searches to go through a list of bugs, it can be very useful to not use the default tabular layout but to switch to the “Long Format”. This shows all bugs in the search result aggregated. That is you have all the comments and all bug fields. A quite useful feature also when searching for a duplicate. Unfortunately this view cannot be used to edit bugs, for that you still have to properly open the bug.

Bko also keeps the context when you open a bug from a search result. That is on each bug page you have pagination to navigate through the search result. If you change a bug by default bko will also open the next bug from your bug list, but you can change this behavior in the preferences.

This is the second post in my blog series: bugs.kde.org for developers.

For an Open Source developer email is one of the most important developer tools. We communicate on mailing lists, receive review requests through emails, get notified about new user support questions in the forums, ensure that all commits had been reviewed by using the commit filter and so on and on. If you are a developer interacting with bko you should probably already know that you can receive mails from bko. But there is much more into it.

Why receive mails for Bug Reports?

Getting mails for bug reports means that you have all your development discussion in one place: your email program. It is very easy to escalate a bug report by just forwarding it to the mailing list. But that is not the real advantage of it. Consider you want to answer to the user, how do you do that? Well of course you go to the web application. No! You press reply and send the mail to bko. All mails sent from bko have a reply-to header set to ensure that your reply will end up in the bug tracker. This makes it very easy to just reply to a comment on a bug.

Another advantage is that you start to collect a local copy of the bug reports and history of your product. Up to now I have collected close to 27,000 bug mails for kwin in one mail folder. Thanks to Akonadi and Nepomuk it is very easy and fast to perform full text searches which comes very handy when looking for a duplicate. Most duplicates can just be found by filtering for the subject if you have an idea how the bug was called.

Managing Bugs

But you cannot only receive comments and send comments to the bugs, you can do much more. You might not know it, but if you add

BUG: 123456

to a git commit the hook on our servers will send a mail to bko. This means you can even set bugs to fixed just by sending out a mail. For a complete documentation on how a mail has to look like please refer to the documentation on Bugzilla’s mail interface. Btw. if you don’t know that there is documentation about Bugzilla: you can find all available documentation about Bugzilla here. BKO currently uses version 4.2, be aware that not all documented features might be available on BKO.

Mail Settings and Following Users

BKO gives you a very fine grained control on when you want to receive mails for your bug reports. For that select “Preferences” and then the second tab called “Email Preferences”. So you can fine tune when you get a notification. E.g. you might not be interested to get a mail whenever someone is added to CC.

But much more interesting is the “User Watching” functionality on the same page. This allows you to receive emails as if you were the person you are watching. So if you follow a user who will receive emails for those bugs he is assigned to as if you were assigned to the bug. This is a very handy feature if you have a bko account for your project such as “kwin-bugs-null@kde.org”. So I’m following this user and that’s the reason why I complain when someone reassigns a bug to product kwin and forgets to reset the assignee to default: those following the user won’t be notified and the bug is kind of lost (a better workflow for this will be discussed in my next post).

What else?

Since the upgrade of our bugzilla installation bko can send out HTML mails. By default bko sends out plain text mail and I use plain text mails everywhere except for bko. With HTML mails you get nicely formatted tables whenever something changes like for example the component. It is in my opinion much easier to read and that’s why I use HTML mails for bko.

You can enable those in the last drop down of the “General Preferences”.

This is the first post in my blog series: bugs.kde.org for developers.

In this post I do not want to discuss any specific features of bko but want to give some general advice on how to work with bug reports.

The first important advice I want to give you is to remember that the bug reports are there to help you. They are there to improve the quality of your software, they exist to help you deciding what you want to work on. Remember: the bugs are there to help you!

But you have to help bko to become a database which actually helps you. There are bug reports with low quality, with user support questions, dream worlds, wrong assumptions and all such things. What is important is to improve the quality of the bug reports so that all bugs can help you.

To get to a good database don’t wait for others to do it for you. More than 400 bug reports are opened each week, so don’t expect that there is a team of bug triagers which knows all details of your software to properly triage it. Triagers and users can help in reproducing the bugs but cannot help you in turning the bug into pure gold.

When a new bug is reported remember that it will be in bko for quite some time. We are far away from a bug gets reported and fixed in the next release. The report will be in your search results, in your lists for weeks, months maybe years. You will see and read it more than once.

Every time you look at a bug to figure out what it is about you lose time. You did that once and you should not do it again. Remember: the bug tracker is there for you. The more information you put into the bug report the more it will help you. Is the summary line bad? Change it! It will be shown every time in your search result. Does it not contain any way to reproduce it? Add it! Did the user report multiple issues in one bug? Close it and open separate reports!

Yes it is totally fine to discard everything the user wrote. The bug tracker is there for you and not for the user. There is nothing wrong with opening a new bug report with your technical analysis and setting the user’s report as duplicate. If that helps you it’s fine.

Don’t be afraid of setting bugs to invalid. If the user just did not find an option or used the software in an incorrect way, you can safely close the report as invalid and send the user to the forum. That’s where user support happens and not on bko.

If a user is not able to reproduce a bug and cannot tell you what he did, there is hardly any chance for you to reproduce it either which means you cannot investigate it and cannot fix it. It’s a pity but there is nothing you can do about this bug, so you can set it to NEEDSINFO WAITINGFORINFO. If a user finds this bug and can reproduce it, it can still be reopened but till then it doesn’t help you if it sits there and contains no useful information for you.

Your software is no dream world. Yes bko allows the user to enter “wishes”. But you have to question the wishes. Not every wish should come true, not every feature can and should be added to your software. If we want software which does everything and the kitchen sink there is already Emacs for it 😉 So there is nothing wrong with stating that the specific feature request does not fit with your software and that means setting the wish to WONTFIX. I think that is better and more honest than keeping the wish open for years without telling the user that you will never implement it. And remember bko is there for you and not for the user. If the feature request sits there and won’t be implemented it will be shown in your search results, it limits your possibility to work with bko.

In general bko is very bad to be used for feature requests. So just don’t use it for it. If a user reports a new feature request, just set it to WONTFIX and send them to KDE Brainstorm. That allows the users to discuss it, to figure out whether it is a feature for a user’s specific workflow or whether it’s a real advantage to your software.

Sometimes users report “bugs” which are in fact feature requests. Totally valid and correct behavior may seem like a bug to a user. But if your software behaves correctly, it’s not a bug. So the user is asking for a change in existing and working functionality. Those requests should be handled like any other feature request and not like a bug. Remember the bugs are there for you and not for the user. If it is no bug, it does not become a bug because the user yells. And if you think the feature works correctly the way it works, then again it’s a WONTFIX even if the user thinks it’s a bug. And don’t discuss. Users try to discuss such decisions and such discussions should happen – if at all – on brainstorm. Make it clear that discussions won’t help anything, that it takes away your time to fix bugs and if that does not help just ignore the bug or get help from the community working group. Users have no right to question your decisions about which features to implement and which not. If they want it implemented they can implement it themselves, hire someone to do so or whatever. But even then they don’t have the right to get the code in, though they can fork and whatever. Our license does not require that we build a kitchen sink.

And my last advice for today is: don’t expect to change bko for your product in a day. It’s a process which will take months and maybe you will benefit in a year from it. But it’s worth it, so invest the time.

Over the last few weeks I have worked more intensively with bugs.kde.org (bko) – our Bugzilla installation. While doing so I realized that Bugzilla is much more powerful than most of us know and that many of the complaints about bugs.kde.org are caused by us developers using bko in a wrong/inefficient way. Also it seems like there is no proper documentation on how to use bko as a developer. We find lots of information on how to use it as a user or as a triager, but not for developers. No new developer gets mentored on how to use bko, although it would be so important to have also our GSoC students taking part in using bko right from the start.

I want for all developers to turn bko from the monster you don’t want to use into the most important tool for developing your software. With KWin I’m close to that state where I start to benefit from bko and don’t see it as my “enemy” any more.

So I want to share the knowledge I gained for using bko in a blog series. All the posts I will write in the scope of this blog series will be merged into a wiki page. If there is a specific topic you want to have covered in the blog series, please leave a comment to this blog post.