1. 8

  2. 1

    I’m in a process of defining how a changelog is defined and maintained by my company.

    It’s interesting that the linked page discourages using git commit logs:

    Commit log diffs

    Using commit log diffs as changelogs is a bad idea: they’re full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

    The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don’t.

    The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

    I think I would rather keep the logs clean and readable (rebase etc.), or have each feature as a merge commit to master and generate the log from that.

    I’m using the same approach for work logs that are mandatory where I work. Worklogs are solely generated from commits. That encourages me to write readable, clean commit messages (no “fix typo”).

    I wonder what’s the experience of people here?

    1. 3

      I’m a big fan of keeping commit log and changelog separate.

      To me the commit log should tell the story of how the project has evolved from a maintainer perspective – with atomic commits for every small aspect.

      The changelog on the other hand should tell the story of how the project has evolved from a consumer perspective – with emphasis on new and deprecated features, bug fixes etc.

      Especially when it comes to libraries and frameworks this distinction makes me think the two are distinctly different.

      The consumer of a framework/library cares about the public API and how it functions and works while the maintainer of the same cares a lot about internal API:s as well as tests, code quality as well as cares much more in detail about dependency updates, performance tweaks etc. Even a bug fix that merits one single line in a changelog could merit multiple individual commits in the commit log as the public facing bug fix could be a symptom of a much larger issue with the internal code.

      1. 1

        Interesting approach. But you can have multiple commits in a topic branch (atomic commits) that is merged to master and that merge commit would be one visible change to the consumer (“Fix bug X”, “Implement feature Y”). Then the changelog would be just commits directly in master. The added benefit is that you could revert such feature wholly.

        Thanks for your input!

        1. 2

          Yeah, there are ways to embed the consumer oriented changes inside the commit log and make the changelog a subset of the commit log. The “Conventional commits” standard is another such approach: https://conventionalcommits.org/

          One tricky thing with the merge approach is that simple UI:s like GitHub wouldn’t separate the merge commits from the commits it merges in but rather just list them all in the same list – so unless one use a tool that shows the full tree, rather than a simple commit list, then it will be hard to easily separate the important commits from the non-important ones with that approach.

          1. 1

            “Conventional commits” seems very interesting.

            I agree that the merge approach would require some special tooling and can look bad on GitHub but I’m going to give it a try and see how it pans out…

    2. 0

      I was disappointed to read that the “release” of Keep a Changelog was just this website. I like that it is demonstrated what the idea is all about. However, I am not convinced that this demonstrates a lot of effort; anybody can come up with arbitrary rules to keep a changelog. So I would doubt that the proposed idea will have wide spread application.

      Seems like just another “hobby project” to me.