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.

I am looking for a good release notes template. Possibly in a plain text or HTML form. What do you guy use?

EDIT: I forgot to mention that these notes will be used internally in our company for other developers using our libraries.

I am interested in what you believe a release note should and should not contain. E.g. do you list all open issues or just issues closed in this release? Do you maintain all previous release notes in the same file (possibly in reversed chronological order), or have separate documents for each release?

A couple of examples that I have found on Apache web site:

share|improve this question
    
It really depends on where the release notes are going to be placed. If it's on a mailing list, they should be plain-text. If it's on your own web site, you can use HTML. Short and to the point is better than long-winded detail, though avoid jargon if you can. –  TZHX Apr 8 '11 at 9:55
    
Please point to any example of these "Release Notes" you've seen. Really. Please update the question with an example that you like so we can comment on it. –  S.Lott Apr 8 '11 at 10:12
    
Which of those two examples do you like better? –  S.Lott Apr 8 '11 at 11:20
add comment

1 Answer

up vote 2 down vote accepted

It could also depend on what you're buildung and how. Our artifacts are primarily in Java, and our build system is Maven so we use the maven generated site for documenting artifact details. Specifically talking about release notes there is the maven-changes-plugin which generates a pretty HTML report with descriptions of what has changed and links to our bugzilla bugs, from a managed xml file we keep with each project. I believe it has the ability to auto-generate such information from JIRA as well (but we don't use that). Other plugins generate reports on code coverage, dependency versions, static analysis results, making a nice neat package for all of our internal developers to see.

Edit in response to your edit ->

I think that release notes targeted at developers should contain all issues resolved with the current release. If you were targeting a set of notes toward non-technical folks (e.g. a final application instead of a library), I think that could only contain high level, functional issues that were resolved, as they wouldn't necessarily be as interested in the technical nitty gritty, just what such changes would mean for end users. I think the notes should contain a link to your issue tracker, so people can see and search for open issues (or in the non-technical case, dig deeper into closed issues), but I don't think listing open issues in your release notes is necessary, because you might always find more issues after release, and you don't want to get into a cycle of having to update your prior release notes every time. (If there is a really really big super major issue, you might warrant an update, but as a rule of thumb, I don't think it's worth it)

We currently do maintain all release notes in the same file (by version, current version at the top), because it's much easier for me trying to determine when X issue was fixed, to scroll through one page, instead of through several pages. I could see if the notes get rather long, you might break it off at a certain point and just link to older release notes, but that would be after several sets of versions. (Admittedly we're using maven sites, and we keep the site for all the previous versions as well, so we can peek back that way too).

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.