add a "changelog" or "history" section to versioned documents

[jbmaillet]

CVE Numbering Authority Operational Rules (CNA_Rules.md) version 4.0.1 has been released last week.

git allow for easy diff'ing on markdown files, but for non-git users and/or for a high level view, a "changelog" or "history" section could be useful, just as in the public announcement here:
https://www.cve.org/Media/News/item/news/2025/05/13/CNA-Rules-Updated-to-Version-4-1

[jbmaillet]

A new 2.0.0 version of the dispute policy has been published:
https://www.cve.org/Resources/General/Policies/CVE-Record-Dispute-Policy.pdf
...but no changelog nor change in the markdown document here. This would help tracking the changes.

[zmanion]

Hi, I think this is a good idea to add, want to get some input from a couple working groups at least, and can think of a few ways to implement it. Do you have any preference or other thoughts on how the changelog should look?

1. Just use git/GitHub, e.g.,

(CNA Rules)
7cc0028...2fbfcdc#diff-74734f54797ef9d6cd30e3ad39f5c3b50c71a10c0f4cb94eb5bb289bebf5fe85

(Dispute Policy)
master...dispute

2. Inside/at the end of each document.

3. As a separate single file for the repo.

4. As a separate file per document.

One consideration, the most official versions of these documents are PDFs on cve.org. So if those PDFs do not contain the changelogs internally, we may still want cve.org to host or link to the changes.

As I write this comment, I think that saving a copy of the markdown diff at each revision may be the highest fidelity and least effort. So another question is whether we want to create a summary also, that is, both a full diff and a changelog/release notes style summary of changes.

[jbmaillet]

the most official versions of these documents are PDFs on cve.org

Understood and agree.

Inside/at the end of each document

Because the pdf is the source of truth, and because some people are not well versed in git / GitHub (non-devs, managers / execs), I think the Changelog should be part of the document itself, be it the markdown or the pdf (presumably generated from the markdown).

As I see it the changelog should not be the full git diff, nor the log of all git commits titles: git is already there for this level of details. Rather a human made and human readable synthesis of what changed, and possibly why. Because of this, the changelog should be human generated. Something in the spirit of:
https://keepachangelog.com/en/1.1.0/
Or:
https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
...except again that I suggest it'd part of the document itself.

both a full diff

This git repo provides the functionality for that, as long as markdown sources are committed in sync with a new release. No need to duplicate the functionality.

a changelog/release notes style summary of changes

Yes , I was thinking about this style of changelog.