From 7e9fc87f34b71acbeffd8cad8c30a9171ffe85c0 Mon Sep 17 00:00:00 2001 From: Kai Lueke Date: Mon, 3 Jan 2022 15:01:43 +0100 Subject: [PATCH] changelog/README.md: describe purpose of the changelog entries The changelog entries should be directly used for the release notes, thus they need to be short and hold only information relevant to the end user, and should be in the markdown bullet point format. --- changelog/README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/changelog/README.md b/changelog/README.md index 8c61ac11cc..4a94640eed 100644 --- a/changelog/README.md +++ b/changelog/README.md @@ -9,9 +9,17 @@ into the repository. The changes are essentially divided into 4 categories: Based on the category the PR falls into create a new file in the respective directory with the filename format `YYYY-MM-DD-.md` -(can be generated via: `$(date '+%Y-%m-%d')-.md`) +(can be generated via: `$(date '+%Y-%m-%d')-.md`). +The file should contain a markdown bullet point entry (`- TEXT...`). -The contents of the file should describe the changes in an elaborative manner +Example for the bugfix section: + +``` +- The Torcx profile `docker-1.12-no` got fixed to reference the current Docker version instead of 19.03 which wasn't found on the image, causing Torcx to fail to provide Docker [PR#1456](https://github.com/flatcar-linux/coreos-overlay/pull/1456) +``` + +The contents of the file should describe the changes in a concise manner, +and only contain information relevant for the end users. (use the past tense for the change/bugfix description to avoid confusion with the imperative voice for actions the user should do as a result). Security fixes of upstream packages and package updates can be kept short in most cases