Communicating important internal changes to the user

[nikita-kiryanov]

I understand that changelogs document changes that the users care about, and that usually, internal implementation details don't fall into that category. However, I think that sometimes internal changes are worth being communicated to the user:

Let's say that you did some big fundamental change in the backend, like rewritten a core component of the application, or switched to a different rendering engine, or switched parsers, and so on... Something that affected the inner workings in a major way, but shouldn't be noticeable from the outside. This means that the resulting changelog can seem rather innocuous compared to the fact that your app is now significantly different from what it used to be:

You haven't Added new features, and you also can't say that you Changed existing functionality (although, it's not obvious to me how generic the meaning of Changed should be, so maybe Changed is a perfectly good section for what I'm suggesting, but it's not clear to me from its description). Nothing about the user facing part was Deprecated, no features Removed. It's possible that the change Fixed some bugs and improved Security, so maybe you can mention these aspects in the changelog, but it's likely that the whole thing would look like a minor update, and the user will be walking into a situation that is actually more dangerous than what it seems, because the likelihood of new bugs is not negligible, and maybe high stability is really important to the user.

It seems reasonable to me to give users a fair warning that "FYI, we replaced a big chunk of the backend, so even though the list of frontend changes seems small, it's actually a major update, and if stability is critical to you, you may want to wait a version or two for the undiscovered bugs to be smoothed out".

The question is, how to do this? Is the Changed section a good candidate, or is it reserved for actual functional changes to the features, not the inner workings of the features? If so, a new category might be necessary, because as I described above, the other existing categories don't quite capture the nature of such a change. Maybe something like Internal might be fitting.

[tuukkamustonen]

I second this. While internal/technical changes are "irrelevant" for the use of software, they may be of interest to people. Or you may want to highlight some technical adjustments for the conscious-minded readers (it's easy to skip Internal section, if reader is not interested).

[st-pasha]

What about keeping a separate changelog, just for these internal changes (or other things you may want to communicate to the developers' team)? It could be called CHANGELOG-INTERNAL.md for example.

[nikita-kiryanov]

The point of this suggestion is that sometimes non developers also care about internal changes.
For example, if you completely rewrote the payment management system I'm using, I might want to wait a few versions before upgrading. If you switched a graphics library, and now I'm having display issues, I might be able to figure out that I need to dump the reverse engineered free software driver for my GPU and install the official Nvidia one. Etc etc.

[shadowspawn]

I think it is appropriate to put internal changes into the CHANGELOG if it is potentially useful to readers. I use whatever section makes most sense, which is often the Changed section.

For example I often include a dependencies entry when I have updated npm modules my project depends on.

Changed

• dependencies