changelog diffcheck

[koppor]

After a release, the CHANGELOG section of that release must not be altered. In case the development workflow of a project is to manually edit the CHANGELOG, it might happen that changes come in:

1. PR is made on main.
2. PR not merged.
3. New release on main.
4. merge into main.

I need a check at step 4 to say: "Frozen CHANGELOG.md section changed". I would implement a CLI like that:

git diff HEAD..main | changelog diffcheck

Returns error level != 0 in case a frozen section is touched.

[NiclasvanEyk]

I think it would be hard to parse diffs properly. We currently don't know the line numbers of each release, only their character/rune offsets in the file. I also have no interest in implementing something like this, since I feel this does not fit in with the existing features.

That being said, you could solve this problem with a combination of clparse and some jq:

diff \
    <(git show main:CHANGELOG.md | clparse --format=json - | jq '.releases[] | select(.version != null)') \
    <(git show HEAD:CHANGELOG.md | clparse --format=json - | jq '.releases[] | select(.version != null)')

This works as follows:

1. git show BRANCH:FILE just prints the changelogs contents on the given branch
2. clparse --format=json - reads from STDIN, parses the changelog and produces JSON like this:

   {
     "title": "Changelog",
     "description": "All notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n",
     "releases": [
       {
         "version": "1.0.1",
         "link": null,
         "date": "2023-09-10",
         "changes": [
           {
             "added": "A shiny new feature"
           },
           {
             "fixed": "an important bug"
           }
         ],
         "yanked": false
       },
       {
         "version": "1.0.0",
         "link": null,
         "date": "2023-09-10",
         "changes": [
           {
             "added": "an existing feature"
           },
           {
             "added": "another feature"
           }
         ],
         "yanked": false
       }
     ]
   }

3. jq '.releases[] | select(.version != null)') parses the json, selects the releases and filters out the [Unreleased] section (or any other section without a version. Since these are not 'frozen', they are allowed to be changed.
4. diff <() <() simply compares the output of the two resulting strings.

The exit code is 0 when the strings are the same, so for your use-case when everything is fine, and 1 if a frozen section was changed.

[koppor]

Thank you so much for providing this command line magic! 🤩

[koppor]

In case someone finds this issue via Google. The proposed script works only if versions follow SemVer.

• Code of clparse: https://github.com/marcaddeo/clparse/blob/deedfa9fc535bb5322ff2eda7f3e7e21e027ff7f/src/lib.rs#L170
• Issue: Support non-SemVer and en dashes marcaddeo/clparse#22