Release Notes

[kiwisincebirth]

Hi Wayne

Referring to RELEASE_NOTES.md is was specifically thinking it would be good to include documentation about all the new significant features that are included in the release, like a much smaller change-log but with. each new feature described in a couple of sentences, but it is a narrative, ie. what, why, who, etc.

WHY?

It is so existing users can get pointers to things that have been added which might be of interest to them. Without this either

• Users have to read the change-log which can be a bit cryptic, and hard to understand.
• Users just use the software as they have done before, and ignore new features

Also

• I did notice a (spoke before?) a you-tuber publishing video, but still using hd512 not aware why to use hd1k. could be helped by release notes, maybe.
• Also personally I have invested some effort into improving this software would be good to let people know about it...

Mark.

[kiwisincebirth]

And Unrelated

The file Source/Readme.txt - contains a dump of a build from a while ago. Is there a good reason for it ? Can it be removed ? I noticed it because when searching the repository (a code search) it does tend to show up in a lot of searches, which is distracting.

[wwarthen]

Hi @kiwisincebirth,

Sorry, I am really swamped trying to finish testing and handling some unrelated personal stuff.

Regarding the Release Notes, I have mixed feelings about adding a section on new features. My intention was to have Release Notes super-focused on stuff that users would need to be aware of when upgrading. A list of new features would likely be very long and I am worried it would result in TLDR. When I do a new release of RomWBW, I do generally post an announcement in the various forums and include a very brief list of new features. I generally like the idea of a more robust list of new features (and I agree that the ChangeLog does not cut it). I am thinking that perhaps a separate "Announcement" file could be added and include a good list of enhancements. Both the Release Notes and the Announcement files could be referred to in the forum posts and the GitHub Release page.

Regarding the Source/ReadMe.txt file. I included a dump of a typical build output because I used to get a lot of questions about "is this normal" related to builds. However, I do now include a "make.log" file in the root of the distribution which shows the full results of the complete distribution build. This file is probably sufficient for people to refer to. I will probably remove the dump from the ReadMe.txt file as you suggest. I generally review all documentation as a final step prior the release.

Thanks, Wayne

[kiwisincebirth]

Hi @wwarthen

Hope everything going well.

A seperate Announce file would be fine its really up to you where it goes, so long as its easy to find . I agree about giving too much information, I think this document could be shortish. Here is an outline of what I would see as important to communicate

• New Hardware (a simple bullet list would suffice)
• New Features (a paragraph for each feature)
• Changes to existing Features (a paragraph for each)
• Bug Fixes (NOT included, refer to users to change log)

Ill leave it with you.

Mark

[wwarthen]

Yeah, I think I may need to just try a few things and see what I like in the end.

Thanks for the suggestions.

-Wayne

[wwarthen]

I have attempted to address this in my latest commit (a8ee0ca). Not sure how I did, so interested in feedback.

Thanks, Wayne

[kiwisincebirth]

Hi @wwarthen - Thanks I have improved on some of the points in release notes to provide (slightly) more description. Also Note in the PR there is second commit with some minor general improvements that I hadn't previously found time to commit.

The section on DOS 65 (which came from a readme) is the biggest change. Debated with myself if though it should be there, but it is mentioned elsewhere in the document, so thought that was good enough reason to include it. Noting : If reasons for you to not include it completely fine with me, just search wider in to doc if removing 😄

See #501

[kiwisincebirth]

Just saw the merge. Hope the descriptions are better, still brief, but just generally more descriptive. IMHO

[wwarthen]

Everything looks great. I really appreciate the help on the doc!