In terms of collating the changes, I think they should be documented whenever new code is committed to the master branch, as in my experience trying to do it just before a release becomes too hard and things get rushed (the entries in the file are minimal and not very helpful), or missed altogether.
My solution to this for my work projects is that each application has a ReleaseNotes.txt file with an unfilled-in release header (e.g. "Release %version% - %date%"), under which I just add a new entry just before a branch is merged back into master, describing the change in a way that makes sense to a user (i.e. not just to me as a developer -- see below for more on this). Then, during a release, the version number and date are updated, the file is committed to the releases branch, then a new unfilled-in release header is added, ready for the new changes. This is done automatically, but it's not a big deal to do it manually either. We obviously don't have a "releases" branch (which, I mean, why not?), but just copying the updated file to whatever packages up the release will work just as well.
This file can simply be displayed to the user, giving them the entire history of changes (rather than only providing the changes since the last update).
I also think that only user-visible changes need to be included (e.g. new/updated configuration parameters or functionality of screens), as purely under-the-hood changes just clutter things up and don't help the user. They should also contain enough detail that the user is clear on how they can use the new feature or how it affects them (by adding the entries when they're developed, this becomes a lot easier!).
Note that there is definitely a bit of an art to describing things from a user's point of view, especially when developers can be so intimately familiar with things that aren't entirely obvious to a "normal" user. As an example, there's a post in this forum about the "Single EPG", and I honestly don't know what that is, or how to view it. Maybe I already use it and am just not familiar with what it's called (the manual doesn't refer to anything using that term)? There seem to be a few terms that are used in the code that aren't used in the manual, or are at least somewhat confusing enough that I struggle to map them to the actual function on the box. I'm willing to accept that this may be a "me" problem, but I suspect others struggle too. In the changelog, it could be helpful to always include the button presses required to invoke the function being talked about (especially in terms of config options actually... just randomly include a config name without telling a user how to find that option isn't overly useful).
It's currently very hard to know what's changing between beta updates (and hence what we as users should be looking out for when an update happens), and it's going to be even harder for those not on the beta to know what's changed when a new production release happens -- although I admit that putting in all of the changes that have occurred since the last production update may be too hard, and so this is probably only something to add post the next release.
Note that for a production release, perhaps it would be worth adding a new entry to the file that collates all of the major changes, making it easier for the user to see the big changes that may affect them, but they can also scroll through to see all of the individual updates if the wish.
Thoughts?
Sorry that this has turned into a bit of a saga, but it kinda hits a few pain points that I have with the current system. I also wanted to provide an easy-ish way to implement it, rather than just complaining
.
