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.
“If I had to say anything there would be a git hook to forbid pushes to stable branches without BUG and FIXED-IN fields” I agree with this. Every time a maintainance release comes out and I check the change log I feel it is a bit dissapointing to see so little changes. Well now I know there are a lot more changes then in the changelog that comes with the relae so it would really be nice to see everything that was changed. This would show how much work KDE developers actually do with each realease and I guess it would also help convince distributions to actually provide updates. And I don’t only mean bugfixes but also other changes, like performance enhancements and others.
I am not sure but doesn’t KDE Telepathy use Milestones? At least they plan a lot of their efforts on BKO, using “Bug depends on” and such to evaluate which bugs are the showstoppers and important ones.
I checked telepathy before writing that statement
We don’t use the “target milestone” entry, but we do something very much like what you’re doing.
Instead we have what we call “tracker bugs” which depend on everything we want to fix for that release. Up until the feature freeze it contains a list of all the features we want to add, after the feature freeze any remaining feature requests get removed from this, and it becomes used for tracking any bug that should be fixed before the release.
Here is our current one: https://bugs.kde.org/show_bug.cgi?id=291062
Why do we do this instead of “target milestone”?… because we didn’t know about it 🙂 I’m not sure whether it would fit our workflow better or not.
I think we do have two key differences to your workflow.
Firstly, although we have fixed dates for freezes, we release when nearly all the bugs are closed, not on a strict fixed 6 month cycle like you have in core KDE. Another difference is that I’m perfectly happy with end users adding bugs (actual bugs, not features) to our tracking bug.
Yeah that’s very similar, in fact I think the two workflows are exactly the same just that you use different features for it. The target milestone does not have anything to do with time based features, you probably know the next version number and that’s what matters. Or you could also use the freeze date as target milestone – it’s free text, after all. So I would suggest to evaluate whether it makes sense as you could use bug dependencies for something different – like tracking dependecies 😉 Bug dependencies will be the next blog entry btw.
Will definitely consider changing for 0.5.
Arguably it is a dependency, it used to be called “release KDE TP 0.x”, which was a bug for doing all the tagging and uploading tarballs, which can only be done after everything has been made, but mile stones seem to fit what we’re doing better.
It can be a useful to have a bug for having the release, so we can comment on what other stuff we need to do for the release. Though now we’re starting to know what we’re doing (or at least pretending to!) that’s less important.
I couldn’t agree more. It is quite sad to see how many products in b.k.o have such a sorry state of versions. I am not talking about the unmaintained ones but the very much alive and kicking products who seem to totally neglect their b.k.o part.
For those too lazy to take care of that, please ask us bug triagers to do it for you in #kde-bugs, but please, do something! You can’t imagine how difficult it is to triage when a product has no proper versions set.
And a strong+1 from me: do not commit a bugfix without the BUG and FIXED-IN field, there is no excuse for sloppy work there. We are committed to quality and this is just one little step towards it.