Releasing software and the importance of Changelog.md

I've been reviewing some links on how to properly set up a changelog.md file when displaying software release notes for each version. It's important for consumers of your software so they know what has been updated in each release as well as a way to make sure your development team is on board with writing helpful notes in order to do clean up.

Things to note

 

It's not a git log dump to the file

  • You don't want to throwup your log file for people to try to peruse

Date format and general consistency

  • Use an ISO format like YYYY-MM-DD
  • This should go the same for JSDocs for consistency
  • Have heading for enhancements, features, bugfixes, deprecated
  • Nice to output in markdown format for web display

Here's a few samples and links to start working with them

 

Keepchangelog.com

keepchangelog.com screenshot

Github releases

https://github.com/blog/1547-release-your-software
Github has a Releases tab and workflow that allows you to enter notes and upload a distributable file
screenshot

Generating changelog from git log

https://coderwall.com/p/5cv5lg/generate-your-changelogs-with-git-log
screenshot