DEV Community 👩‍💻👨‍💻

Discussion on: Blog post: Why and How Should You Write a Good Change Log

dan503 profile image
Daniel Tonon

If you are using GitHub as your repository host, I would recommend authoring release notes rather than maintaining a change log. Autoprefixer has a pretty good releases page as an example.

The benefits of GitHub releases:

  • adds a link to the exact commit the release was made on
  • automatically adds a time stamp
  • adds download links so users can download a copy of the repository in the state it was in at the time of release
  • displays the text as rendered rich text when reading it rather than as markdown.
  • it has an easy to access consistent link on the home page of the repo (The "releases" button)
  • people can send a link to a specific release to a work colegue
  • it takes significantly less time to write
  • it looks pretty
jonasbn profile image
jonasbn Author

Hi Daniel,

That is good advice, my goal with the article was however not to promote or require any special tools or platforms. The change log accompanies the release and your consumer might not have online access.

Anyway I do use the GitHub release facility in conjunction with the change log file accompanying my software myself. The software is distributed via other channels, I just copy my entry from the change log file into the text field for the GitHub release (see example Perl distribution example).

This would work for a lot of software, like Perl distributions or Visual Studio Code extensions etc. where the change log is being made available for consumption by the toolchain or similar. Other distribution channels do seem to approach this differently where nuget for .NET seem to lean on linking to facilities like the one you mention.