From 913cf7d52f7c3ec26389c825d2dbd662e142190f Mon Sep 17 00:00:00 2001 From: Oliver Davies Date: Tue, 27 Jun 2023 22:40:37 +0100 Subject: [PATCH] daily-email: add 2023-06-23 Why keep a CHANGELOG? --- src/content/daily-email/2023-06-23.mdoc | 40 +++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 src/content/daily-email/2023-06-23.mdoc diff --git a/src/content/daily-email/2023-06-23.mdoc b/src/content/daily-email/2023-06-23.mdoc new file mode 100644 index 000000000..4996fe4bc --- /dev/null +++ b/src/content/daily-email/2023-06-23.mdoc @@ -0,0 +1,40 @@ +--- +title: > + Why keep a Changelog? +pubDate: 2023-06-23 +permalink: > + archive/2023/06/23/why-keep-a-changelog +tags: + - changelog +--- + + +## What is a Changelog? + +A Changelog is a file that documents changes made to a codebase. + +In its simplest form, it's a plain text file within a code repository, or it can be written in Markdown or reStructuredText or kept within a separate tool like Confluence or Sharepoint. Regardless of where it's kept, the main thing is the content. + +It's not a copy of the Git log. It's a summary of the changes to be read by humans and for them to see what's changed, not a list of Git commits. + +If you're considering using my open-source package, you can see what changes I've released, when, and what changes are due to release. + + +## How is it structured? + +Each version should have a heading specifying the version number and/or release date and a list of changes grouped by their type - whether something was added, changed, deprecated, removed, etc. This works well if you use conventional commits! + +I like to follow a format called [Keep a Changelog](https://keepachangelog.com). + +The headings link to a diff so you can see all of the commits and changes made to the code, and there's an `Unreleased` section that shows commits that have yet to be tagged and released. + +If you need to present changes to a review or approval board, having an easy-to-read list of changes, separated by their type, is a much clearer format than a list of Git commits. + +## When should it be updated? + +I recommend continually updating the Changelog rather than leaving it to just before a deployment. It's quick to add it to the `Unreleased` section as part of the commit and update the headings later. + +## Can I see an example? + +Sure. See the one I added to the [National Rail Enquiries feed parser library](https://github.com/opdavies/national-rail-enquiries-feed-parser/blob/main/CHANGELOG.md) I've been working on or the [Tailwind CSS starter kit theme for Drupal](https://git.drupalcode.org/project/tailwindcss/-/blob/5.x/CHANGELOG.md). +ure. See the one I added to the [National Rail Enquiries feed parser library](https://github.com/opdavies/national-rail-enquiries-feed-parser/blob/main/CHANGELOG.md) I've been working on or the [Tailwind CSS starter kit theme for Drupal](https://git.drupalcode.org/project/tailwindcss/-/blob/5.x/CHANGELOG.md).