-
Notifications
You must be signed in to change notification settings - Fork 3.6k
Description
I like the Keep A Changelog proposal, but one thing that I think can be expanded upon is that changelogs aren't just used to denote changes to the technical details of software, but also changes to the project itself. The reason why GNU and a bunch of other organizations refer to the changelog as a "News" or "History" file is that it's not just documenting changes but also presenting the user with general information relevant to the project. You can have this be in a separate file, but generally when you update software the end-user wants to see all of the relevant changes in a single notice and be done with it.
For the above reasons, I propose adding a specification for a "Notes" or "News" section, to indicate changes to a project that aren't covered by the other sections. For example, the license agreement changing, support for certain systems being dropped, or the long-term goals of the project changing. This can function as a place for general notices relevant to the end-user which aren't, strictly speaking, additions, subtractions, or changes to the functionality of the software itself.
A reasonable objection might be that the purpose of a changelog isn't to function as a general news document, but to document the changes to the software itself. However, I would argue that presenting important information to the user in a single document is more helpful than spreading it out between multiple documents (which, given that such documents are often named NEWS or HISTORY, might be alphabetically distant from CHANGELOG in a directory listing) and it provides a better user experience by lessening the burden on the end-user. Furthermore, since changelogs are often displayed to the end-user after an automatic update, they may reasonable assume that all of the information they need is contained in that changelog, so leaving out information that isn't strictly technical in nature may result in information being withheld from the user, which is not in the spirit of the proposition of Keep A Changelog, in my opinion.