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.

[zmanion]

Rasing this issue again as we're planning a set of rule changes. As the changes are staged I'll include changelog language. While I appreciate the value of having the changes within the document, I'd like to ask once more if it is better to have a separate document. Also we should follow whatever convention we decide with all of the tracked policy documents in this repo.

My main concern (and it is not significant) with an in-document changelog is the unbounded growth.

Also we could include an in-document changelog with this next revision and later decide to pull the changes out into a separate document.

[jbmaillet]

As for me I would not be bothered by unbounded growth. This is the destiny of changelog's for long-lived, hence presumably successful, projects or documents. As I see it, again, it should be "human made and human readable synthesis of what changed, and possibly why", the important word here being synthesis.