Changelog should identify changes that impact user developments

[ejgallego]

As of today, the Coq changelog doesn't distinguish between changes that impact compatibility at the .v file level, and those that don't.

This makes hard for users to analyze and identify possible compatibility impact when upgrading to a Coq version.

Other systems [for example OCaml] special mark those changes, and IMHO it would useful to do so for Coq too.

[Zimmi48]

Could you be more specific on what you mean by impact (e.g. with examples)? We do already have a Changed category and we only include user-visible changes in the changelog.

[ejgallego]

The wording used by OCaml is "changes that can break existing programs", for example see https://ocaml.org/releases/4.12.0.html#Changes

Our changes category seems more general, doesn't it?

[Zimmi48]

Yes, but I'm curious how frequently they are used for other purposes in practice. Skimming through the list of Changed entries, it seems to me that almost all the occurrences that I've looked can be qualified as "changes that can break existing programs" and the rare exceptions are mostly changelog items that were miscategorified (e.g. "Changed: Added the ability for coq_makefile to directly set the installation folders, through the COQLIBINSTALL and COQDOCINSTALL variables" which should have been "Added: Ability for coq_makefile to directly set the installation folders, through the COQLIBINSTALL and COQDOCINSTALL variables").

[Zimmi48]

FTR our types of changelog entries are taken from https://keepachangelog.com/en/1.0.0/.