42

Is there any sort of guidelines or best practices on how release notes should be written? I guess I am trying to find the proper balance between making the point without being too specific. Also, do developer usually provide a much more release notes for QA team compare to the one submitted for public view?

ROMANIA_engineer
  • 54,432
  • 29
  • 203
  • 199
DeFiNite
  • 583
  • 1
  • 4
  • 7

7 Answers7

30

Public release notes should contain at least:

  • release, buildnumber
  • all fixed public bugs
  • all added public features

QA release notes should contain at least:

  • release, buildnumber
  • all fixed bugs including bug number
  • all added features including links to design docs

Consider your audience and try to think what they need.

An other thing to add is new or discontinued support for certain platforms. (For example we quit support for Win3.1 and added Vista 64 bit).

Toon Krijthe
  • 52,876
  • 38
  • 145
  • 202
  • 2
    Some additional points: - Publish in plain text or at the very least html. Don't make them hard to view. - It is common to append release notes onto the top of older release notes. - It sometimes good to refer to significant known bugs not yet addressed. – Arnold Spence Mar 12 '09 at 12:44
  • Nice addition. I would definitely go for plain text. But if you can generate the release notes, there is no reason not to inlcude html, pdf etc.. – Toon Krijthe Mar 12 '09 at 12:46
22

I would take a look at the release notes of popular F/OSS projects:

All these projects have pretty readable and balanced release notes.

Tomas Kubes
  • 23,880
  • 18
  • 111
  • 148
Can Berk Güder
  • 109,922
  • 25
  • 130
  • 137
11

If you have an project-management/issue-tracking system, you should definitely be using that to generate your release notes. Trac and Redmine in particular are very good at this.

Release points should have a few properties, IMO:

  • Remember your audience. If this is an iPhone app, few are going to care about the fact that a particular logic error on line 572 in the Foo class was fixed. But they'll care a lot about "app is now accelerometer-sensitive".
  • Summarize the new developments, features, and bugfixes in a broad, sweeping way if possible. If you can tie these together thematically (e.g. "we implemented generics and anonymous types"), a short blurb about that is a good way to give people the big picture.
  • Itemize the specific things that were fixed, with links to your public bug-tracker, if any. This can usually be automatically generated.
  • Don't provide excruciating detail. One- or two-liner summaries of each thing that was added or fixed should be sufficient.
  • Always include specific release identifiers (e.g. "v.1.4.5"), as appropriate.
John Feminella
  • 303,634
  • 46
  • 339
  • 357
2

It really depends on the audience. For technical users (for example developers who use your API) you can be very technical. On the other end high-level end users of an application you created might only be interested in new features and major changes.

In between are non-technical users who need the details too, for example support department. For those people you can give a detailed description without the low level technical specifics, for example "Fixed a bug where the record wasn't saved in the database.".

Gerrie Schenck
  • 22,148
  • 20
  • 68
  • 95
1

One best practice with release notes in my opinion is automation. If there are certain best practices for revision control system submit messages (http://drupal.org/node/52287), you can create release notes by an automated script (http://cvs.drupal.org/viewvc.py/drupal/contributions/tricks/cvs-release-notes/). This would create realy nice release notes: http://drupal.org/node/226165

Mork0075
  • 5,895
  • 4
  • 25
  • 24
0

Main contributor of Release Notes would be your development team. It's a good practice to allow your developers and testers to capture any release notes related information against your workItems that is linked to changesets in TFS.

Then you can use open source project like http://tfschangelog.codeplex.com to generate release notes. It has GUI version and a command line version which makes it easy to schedule your release notes reports on a nightly basis.

Toon Krijthe
  • 52,876
  • 38
  • 145
  • 202
Dharmesh Shah
  • 71
  • 2
0

I find that ReleaseNotesHub works great. It provides best practice for the generation and publication of release notes.

PatrickNolan
  • 1,671
  • 2
  • 20
  • 40
  • Not sure about this. If I search "ubuntu", results are zero. –  Jul 14 '20 at 07:04
  • :) where did you search "ubuntu" and what would you expect to see? – PatrickNolan Aug 11 '20 at 02:20
  • :) Maybe I misunderstood "ReleaseNotesHub", the website is mad. Don't search ubuntu. –  Aug 11 '20 at 15:40
  • He actually means https://release-notes.com/ (which is also Release Notes Hub). The website above is madness. –  Mar 25 '21 at 17:05
  • 1
    Hi @StackTheUser https://www.releasenoteshub.com/ fully automates the generation of release notes from many sources including Azure Devops, GitHub and others. I don't know why you would bother using anything else. – PatrickNolan Jul 27 '21 at 00:59