bip174: update changelog for semver/consistency #2145

following up on #2135 (review).

Per https://semver.org/:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes

Per https://keepachangelog.com/en/1.0.0/:

Changelogs are for humans.

Should you ever rewrite a changelog?

Sure. There are always good reasons to improve a changelog.

I am not convinced that a metadata update like a Status advancement warrants a bump of MINOR, also see: #2143 (review)

I think a status update is reasonably significant.

For instance, "Version 1.0.0 is used for promotion to Complete" -- so it arguably doesn't make sense that the other status updates would be patch.

nah

Closing this, because it was resolved by #2143.

I'd suggest we either:

(a) clarify in BIP3 that it is not following semver but rather rolling a local optimization, requiring that updaters verify it in BIP3 in order to follow it rather than semver, or

(b) drop versioning as it probably adds more discussion than it is worth, as BIPs don't have releases, and as there are many BIPs, and a simpler date:change format, as BIP authors writing changelogs were spontaneously doing, would suffice nicely.

As already mentioned in our other conversations, the usage of the version is already specified in BIP3. It mentions the exact semantics and that it is inspired by semver. I understand that the Version header and Changelog might be confusing to people that don’t read the corresponding section of BIP3, but it’s not clear to me how improving the wording of BIP3 would help inform people that don’t read the corresponding section.

I continue to be of the opinion that the Version header is a useful tool for implementers to track when they should revisit a BIP by taking note which version of the BIP they implemented originally. Without the Version, the benefit of the Changelog would be drastically reduced and would be much closer to just perusing the commit log of the BIP file.

If you have concrete suggestions how the wording in BIP3 should be improved to make it even clearer, please feel free to open a pull request.

If you have concrete suggestions how the wording in BIP3 should be improved to make it even clearer, please feel free to open a pull request.

Will do