Release notes for releases

Main development forum.

Release notes for releases

Postby kimmov » Thu Jul 30, 2009 10:46 pm

Sf.net has replaced the file release system. One thing that changed is how release notes are handled. Earlier releases had one page that had two sections (notes and changes). And text in those sections were written when doing a release. And could be edited later of course. New system is that one released file must be marked as a release notes file. So the release notes are now one (or more?) file in released files. There is no separate release notes page. If user wants to see release notes one must first download that file.

We don't have release notes file that would be proper for all release types. So we need to create a release notes file that is proper to add to file releases. As a file that users look when they decide if the release is worth downloading.

We have Docs/Users/ReleaseNotes.html. That file is edited before each beta/stable releases to contain important release info. But I simply don't have time to do such editing for each experimental release. And I also hate to have different kind of release notes for different release types.

So perhaps we need simple text file that basically has the same info what we used to have in old release notes pages. But as we are creating new important document that is read a lot more often than our other docs we could use some new ideas too.

What format would be good? I myself prefer plain ascii text files. But perhaps HTML would be fine too. At least it looks like SF.net download system sets the mime type correctly so the HTML file should open in browser window for users.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Release notes for releases

Postby gerundt » Fri Jul 31, 2009 6:31 am

Maybe shows SF.net later text release notes file inside the page? Normally there website updates are unfinished and need weeks to get stable! :roll:

Maybe this is a good test for reST + Sphinx? We use first a plain text release notes file and can later switch to HTML or PDF file, if SF.net not update there release note system. (I think HTML or PDF are easier for normal users.)
gerundt
Site Admin
 
Posts: 193
Joined: Wed Sep 24, 2008 8:47 am
Location: Germany

Re: Release notes for releases

Postby denisbradford » Wed Aug 05, 2009 1:19 pm

FYI, we can easily generate PDF from DocBook, if you're comfortable authoring that way, I can set up a transform and customize it however you like.
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Re: Release notes for releases

Postby kimmov » Wed Aug 05, 2009 1:53 pm

I don't personally feel comfortable to author release notes as Docbook. Its just too much work in formatting etc compared to actual content which might be simple list of few fixed bugs. I want to write it by copy/pasting from changelog and perhaps editing a bit.

Sphinx might be overkill too. But of course this is all assuming we keep the release notes format as is. It could be something different also (ideas welcome). Current format is just something I made up when I had to create release notes document.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland


Return to Developers

Who is online

Users browsing this forum: No registered users and 2 guests