A change log is the quickest, most convenient way for users and contributors to identify significant changes in a project as it moves from one version to the next. The log exists to keep users informed. Unfortunately, many open source project leaders have little motivation to provide a meaningful CHANGELOG file and are purely focused on shipping the code. Instead of writing clear, understandable logs for a release, many developers resort to dumping git logs, which are often rife with messy commit messages, into the CHANGELOG file. Olivier Lacan, software engineer at Code School, has created a site and corresponding GitHub repository called Keep a CHANGELOG, with an extensive collection of recommendations for writing better change logs. The project page offers a variety of tips for improving change logs, i.e. how to list releases, recommended date format, sections and labels for classifying changes, and file naming convention. One helpful tip Lacan offers, which isn’t commonly seen among even the finest, hand-crafted CHANGELOGs, is the recommendation for keeping an “Unreleased” section at the top. This helps users track for potential changes in progress for upcoming releases. Maintaining
Share This