Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

When releasing a software update, how detailed should the notes be? Specifically, how detailed should bug fixes be?

share|improve this question
add comment

5 Answers

It should contain everything you want your users to know has changed.

share|improve this answer
add comment

The simplest thing to do for bug fixes is just to list the summary (and perhaps some of the details) and state that it's fixed. If these are online you can link to more detailed information for those that are interested.

The person who reported it will know what the problem is without further explanation. Anyone else can follow the link.

Usually most bug reports are fairly cryptic to anyone who's not encountered the problem, and developer reported bugs often only describe the problem rather than the symptoms that the user will see.

share|improve this answer
add comment

Could it also be dependent on the target audience of the software in question. If it is a tool for developer's they might like to see more detail than something aimed at general users.

share|improve this answer
add comment

Please Please Please document everything you have changed.

Try using the (old) Mil-Std 498 Software Version Description Data Item Definition (SVD DID) In English that's a Release Notes Template

For each change consider documenting

  • Issue ID: e.g. FOO-354 ( older excel exports don't re-import correctly ) nature of issue: defect [or improvement or new feature]

  • what got changed: The excel import function was updated to identify import columns from the column headings

  • why it got changed: the format has evolved over time and will continue to evolve, older formats have some columns missing.

  • what this means to users: in future, excel exports will in future always import, no matter how old.

I know it's more than most people usually do but it is a really professional approach the makes it easy of users to understand what is going on.

Your defect tracking system might have most of this data. Your team might also evolve to having defect documentation that is so professional that your users can get it mostly unedited.

A story to illustrate why this level of detail is good.

Once upon a time , Sun Microsystems issued an OS update to Solaris. Version 2.5 IIRC. Our factory control system had been working pretty well on 2.4. When we put 2.5 into service on one system for testing, an interpreter written in C stopped working. It took me months to work out that the old implementation of strcmp() had been the example one from Brian Kernighan and Dennis Ritchie's The C Programming Language. The example has a substring matching path if one string is shorter than the other. The C standard says the strings are different if they are different lengths. So Sun updated the library to follow the sntard, and the release notes said something unhelpful like "compliance with the ISO C standard". It took me months to find the source of the problem. TLDR; Sun didn't do what I'm suggesting, wasted 3 months of my life.

share|improve this answer
add comment

The only thing I can say is do not consider a source repository log "Release notes". I've seen this on several projects and found them entirely useless.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.