Forums / Suggestions / Better release notes

Better release notes

Next topic

Author	Message
Paul Forsyth	Thursday 28 August 2003 1:03:51 am Could the release notes for version (betas, rcs, final) be rewritten to describe better what has changed between versions? I forgot to mention this at the conference but it would be great if we didn't have a massive list of changes that has come direct from svn commits. I would like to see an overview for individual sections that have changed discussing what is new and what bugs have been fixed (urls,ids preferrably). For example, the current kernel change list needs to be split up into affect parts of the kernel. Also it would be nice if known issues are published for that version, issues you may have found during testing but have workarounds that you recommend. The changelog should still be there but referenced in some way from each section. This information will really help people looking to migrate between versions. As ez 3 becomes more stable and ez 4 starts to be thought about users need better information about changes between versions. Paul
Jan Borsodi	Thursday 28 August 2003 4:03:02 am You mean like a compact summary of important changes? Should this be a part of the release (like Changelogs) or as a document on ez.no? -- Amos Documentation: http://ez.no/ez_publish/documentation FAQ: http://ez.no/ez_publish/documentation/faq
Paul Forsyth	Thursday 28 August 2003 4:34:58 am Most software releases provide the same document with the release as they have on their website, whether it is as a .txt or a .html file, so one version should be fine. Yes a summary of important changes to each area would be nice. For example, the 3.2 beta release has many changes to the kernel which may affect developers working with the 3.1 sdk, translations, so speaking about the big changes there, api's and so on would be lovely. At the very least it should be able to tell developers that they should look at what changes have occured. A big all-in-one list obscures the changes. Of course, you need to balance what users will be interested in low level changes :) I would like to see good high level summaries with discussion of changes within modules, libs and kernels areas and the apis used to communicate between each. The svn list currently has some seperation between areas. If this was augmented with further information along the above lines that would be great. Paul
Paul Forsyth	Thursday 04 September 2003 1:27:32 am Thanks for the 3.2 beta 2 release documentation. I really like the new format! Though I have a couple of gripes, wishes... :) Could the level of detail be improved to state which areas are affected by updates. I notice a few obscure mentions of sdk changes. Could these be specifially assigned to an area, and maybe expanded upon? Most of the changes seem to be for users but i know sdk changes have been occurring. Do you have a list of known issues with a release that you have found through your testing phase? Could the larger issues be posted as part of a release? As Paul B mentions in his comment to the beta2 release the svn log was handy... Im not sure if it is good to include the full changelog as before in the same document. Maybe there should be a seperate document listing the changelogs for all releases... I've seen this used on other projects. Paul