Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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

share|improve this question

closed as too broad by gnat, MichaelT, Snowman, durron597, Kilian Foth Oct 7 '15 at 12:14

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

Possible duplicate of Should my application's README be for developers or users – Snowman Oct 7 '15 at 0:21

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

share|improve this answer

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

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

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

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

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