When choosing a title for a new issue, there are several grammatical options to choose from. Here are four different options for an example issue I just made up:
- Descriptive: “Newlines are not stripped when multi-line headers are parsed”
- Imperative – negative: “Avoid leaving newlines when parsing multi-line headers”
- Imperative – context first: “Fix parsing of multi-line headers: strip newlines”
- Imperative – desired action first: “Strip newlines when parsing multi-line headers”
At my workplace the issue titles alternate between all of these formats, but I keep thinking it’s better to pick a convention and stick to it.
Which option (from the above, or a different one) is the preferred one, i.e. the one that will minimize the effort of developers reading these issues?
Edit: as noted in the comments, different issue types may warrant a different choice of grammar, where an especially important distinction is between bugs and new work. To make the question more specific, let’s say we choose, as msell offers in his answer, the descriptive option. Now let’s look at a suggestion to improve an existing feature:
- “Add city information to geolocation”
If we stick to the descriptive grammar, we should replace that title with
- “City information missing from geolocation”
However, this seems less clear, since the lack of city information is not a bug, it is the expected behavior. The reporter is merely suggesting to improve that behavior. So it seems the imperative option is the way to go with that issue.
Let’s look now at an entirely new feature. Consider these options:
- “No ability to export report to XML”
- “Add ability to export report to XML”
- “Export report to XML”
Describing the current behavior seems even more ridiculous here, but the imperative option doesn’t look so good too. The third option simply describes the new feature itself, which might be the way to go here, assuming the issue has meta-data that indicates this is a “new feature” issue.
- So what’s more important – sticking to one convention, or matching the grammar to the issue?
- Where would you draw the line between a descriptive title and an imperative title?
- When would you describe the current behavior and when the desired behavior?
3
In the title I prefer describing the bug, not the fix. Also as opposed to pdr’s answer, I focus on the actual bug, not what I was trying to achieve. There is plenty of space available in the detailed description for the expected behaviour, background information and even proposals on how to fix the bug.
To help me writing good titles for bugs, I try to come up with a description that sounds good in release notes. Consider the given examples:
Fixed bug #1001: Newlines are not stripped when multi-line headers are parsed
This sounds good.
Fixed bug #1001: Avoid leaving newlines when parsing multi-line headers
It is a little unclear if the bug is about leaving newlines or avoiding them.
Fixed bug #1001: Fix parsing of multi-line headers: strip newlines
While the bug in this format is clear, it sounds clumsy with the repetition of the word “fix” and usage of an additional colon.
Fixed bug #1001: Strip newlines when parsing multi-line headers
This has the same problem as the second example. It’s unclear if the described line is the correct or incorrect behaviour.
Thus I prefer the first example “Descriptive”.
A benefit of this approach is that less effort is needed when creating the release notes, as the information is already (mostly) in correct format. However even if release notes are not needed, this guideline still works well and produces bug titles that are easy to read and understand.
1
Always why, rather than what. From the perspective of the user, what is the actual problem you’re trying to solve? For example,
Search doesn’t work if looking for a string that spans two lines.
It’s impossible to tell from any of your examples. The problem being that you can’t prioritise tasks, unless you have someone handy who knows why those changes need to happen.
If, when creating an issue, you have an idea what the solution is, write that into the comment instead. It’s no effort for a developer to read the whole issue but, when you’re prioritising, you need to look at that issue in the context of other issues. So it’s important to have useful information to that end.
3