28

Based on a comment and subsequent upvotes from Bug reopen vs. new:

Citing bug IDs in patch notes is just.. very unfriendly. – Krelp

It appears at least some people feel that referencing bug IDs in patch notes is not a good idea. I'm a fairly inexperienced developer, so I'm wondering why that's the case.

Community
  • 1
Travis Northcutt
  • 384
  • 2
  • 9
  • 28
    **not citing** bug IDs in patch notes is just... very unprofessional. Kind of trashes the whole point of having an [issue tracker](http://en.wikipedia.org/wiki/Issue_tracking_system) – gnat Mar 30 '12 at 15:12
  • The same reason that posting only links as StackExchange answers is frowned upon -- if you *only* post a link, on SE that is bad because it (1) requires following to get an explanation and (2) may become invalid in the future if the link dies or the contents change. Similarly, putting *only* bug IDs in patch notes (1) requires going to the bug tracker to get an explanation and (2) may become invalid in the future if a the bug tracker system changes. Including a link in a SE answer or a bug ID in a patch note is fine (and actually good practice) as an *addition* to a regular explanation. – Ben Lee Apr 02 '12 at 18:27

6 Answers6

51

In my opinion, it's a good practice, assuming your users have read access to your bug database. There are lots of times when people are waiting on a certain bug to be fixed in order to decide when to upgrade.

I think what's frowned upon is only citing the bug id and nothing else. You should always also supply a description that is understandable without going to the bug tracker. That also allows you to switch bug trackers in the future without entirely invalidating your previous release notes.

Karl Bielefeldt
  • 146,727
  • 38
  • 279
  • 479
  • You can cite via an abstract reference resolver, a.k.a. URL redirect. – Donal Fellows Mar 30 '12 at 14:42
  • As you say, the "Fixed bugs" (or similar) section should include the Id and the title so the reader won't have to look up the bug to understand exactly what's included and what's not. – StuperUser Mar 30 '12 at 14:43
  • 5
    @StuperUser - Id and title, at a _minimum_. – Oded Mar 30 '12 at 15:30
  • What's annoying is to find Bug ID only notations in comments when the referenced bug/requirement ID system is no longer in use. – jfrankcarr Mar 30 '12 at 15:48
14

It is, as said in the quoted comment... unfriendly.

Unfriendly with yourself

Imagine the following scenario. You are viewing the logs in source control. You are wondering what a commit changed. Instead of explaining it in plain English, it tells you:

Solved #1307

You run the bug tracking system, hoping to have something helpful. Bug #1307 is reported as solved. In the description, you see:

Same bug as #1284

Thanks, its very helpful. You have now to navigate to bug report #1284 to read that it's a duplicate of bug #1113 which refers to bugs #1112, #1065 and #1067.

Five minutes later, you have no idea what are you searching for at the beginning.

A much more helpful version control log message would be:

Solved an issue with the users being unable to log on with a password longer than 25 characters (see #1307), by removing applying the same password length policy to the data access layer as the one used in the website itself.

In the same way, in the bug tracking system, the report #1307 could be more self-explanatory, recalling what was the bug report #1284 about, and how the new one is different from the old one.

Unfriendly with customers

This is not the only friendliness issue.

A second one is that by referencing too much with no additional info, you are making the patch notes/version control logs/bug tracking system reports unusable to someone not very familiar with those systems. When you deal with a bug tracking system daily, you know how to quickly navigate through the reports, view multiple reports side by side, etc. When you're a customer with no technical background, you can easily be lost.

Here again, more detailed messages are very helpful than just a reference. Note that you still want to keep references: nothing is more wrong than a bug which is the same as a bug you encountered two weeks ago, but don't recall its ID.

As a note, the same issue exists in many jurisdictions. In France for example, it is not unusual for a legislation to refer to multiple sources, which may change meanwhile. This means that in order to completely understand it, you have to spend sometimes hours in a library, searching for dozens of referred texts, each text having its own references to others.

Arseni Mourzenko
  • 134,780
  • 31
  • 343
  • 513
  • 5
    This isn't a problem with the release document; this a problem with the level of detail in the bugs. A title should describe the actual problem and the body of each bug have Expected Result and Actual Result. Shouldn't bugs as you've described be closed as duplicates? – StuperUser Mar 30 '12 at 14:45
  • Based on your edit. You've cited the Id in your much more helpful message. Did you mean in your original comment that citing ONLY the Ids with no further information is unhelpful, whereas a proper explanation AND the Id is helpful? – StuperUser Mar 30 '12 at 15:03
  • 1
    @StuperUser: exactly. Providing explanation helps people who just want to know what the commit log/patch note/bug report is about, without spending ten minutes reading the referenced content. IDs are still required for tracking and people who need very detailed, precise and complete info. – Arseni Mourzenko Mar 30 '12 at 15:06
2

There's nothing wrong with citing issue numbers in patch notes, provided users can read the issue which is being cited. If your bug database allows anyone to read, citing the bug number can be very useful indeed. (One better, if your patch notes are in a format that allows links, make those issue IDs be links to the issue in question.) This doesn't mean that you should expose all issues to the general public; it can still be useful to have ones that are shrouded (e.g., where they've got live passwords in!)

Citing an issue number where the person reading can't go and look up the details and history of the bug, that's quite unfriendly. Not that citing such issues without the issue ID is much friendlier.

Donal Fellows
  • 6,347
  • 25
  • 35
  • _"where the person reading can't go and look up the details"_ as one who has been such a _person_, I wouldn't call this really unfriendly. I did use issue ID to communicate to support/dev team who in turn had access to issue tracker. The fact that it was invisible to me personally was merely a minor annoyance – gnat Mar 30 '12 at 16:38
2

It obviously depends who the people that will read the patch notes are, and the target users of the software.

But in most of cases, the vast majority of your users simply don't care about what the bug ID is. They don't care why it was broken, what the fix is, or anything else -- they only want to know what changed with a very succinct textual description without having to go to another page for each change.

Citing the bug IDs makes me stop and think, and I - as a user - don't want to think. It's sort of a usability issue.

Take a look for example at the change log of Visual Assist X. All those linked bug IDs are just noise that distract me from understanding what changed. And this is an add-on for a Visual Studio, targeting programmers. And I'm a programmer. If this bothers me, imagine the average user who doesn't even know what a bug tracker is..

PS: I was the author of the comment that sparked the question

Andreas Bonini
  • 1,073
  • 1
  • 9
  • 16
  • 1
    Honestly I find the documentation at the end of that link helpful. It starts out with a summary and then directs me to the details. Microsoft often does a similar linking in KB articles, not that their doing it makes it good practice, but it is certainly widespread and apparently provides value to many users. – Joshua Drake Mar 30 '12 at 17:23
1

A bug ID is mandatory for a point of reference. The reasons:

  • Prevent ambiguity: Two or more bugs might have similar descriptions. So one would need some anchor to distinguish between them.
  • Convenience: When discussing a bug, either with a customer or internally, the bug ID is often used for as a short form. If the ID will be omitted from the patch notes, it will be difficult to discuss about them:

3052 was already fixed, still working on 3077

is more convenient than:

The "application crash on apply button" was fixed, still working on the "NullReferenceException on clicking change user"

KMoraz
  • 633
  • 6
  • 10
  • (1) What prevents you from combining it, as suggested by MainMa? (2) Why are you committing one and a half fixed bugs? Why don't you commit after 3052 has been fixed, before you even start to work on 3077? – JensG Jun 03 '14 at 22:42
0

I would say it depends on your system: I'm lucky that the one I use automatically detects such references in commit messages and adds a link to the ticket stored in the bug tracker, so it's not an issue.

But if I were on a system where it's not available, I'd still mention the ticket ID (that way you can quickly search in logs by ticket ID) along with a short description of what the bug is.

wildpeaks
  • 2,691
  • 1
  • 19
  • 17