From d094c6763c6ddb860580e7d3b4201f8f496a6836 Mon Sep 17 00:00:00 2001 From: Thiago Kenji Okada Date: Sat, 5 Apr 2025 17:13:59 +0100 Subject: [PATCH] news: create an individual file for each news entry (#6747) The current way to define a news entry in Home-Manager is error prone (since you need to type the date manually) and also it is common cause of conflicts after merges because all entries are defined in the same file. This commit fixes this: we can now create individual news entries for each new entry. A script `create-news-entry.sh` also helps to create it in the correct format (with the correct filenames and structure). --- docs/manual/contributing/news.md | 11 +++++++---- home-manager/build-news.nix | 4 ++-- modules/misc/news.nix | 20 +++++++++---------- modules/misc/news/2025-04-02_13-01-34.nix | 10 ++++++++++ modules/misc/news/create-news-entry.sh | 24 +++++++++++++++++++++++ 5 files changed, 53 insertions(+), 16 deletions(-) create mode 100644 modules/misc/news/2025-04-02_13-01-34.nix create mode 100755 modules/misc/news/create-news-entry.sh diff --git a/docs/manual/contributing/news.md b/docs/manual/contributing/news.md index 80e1b0df..0cbbe1a5 100644 --- a/docs/manual/contributing/news.md +++ b/docs/manual/contributing/news.md @@ -10,14 +10,17 @@ If you do have a change worthy of a news entry then please add one in [`news.nix`](https://github.com/nix-community/home-manager/blob/master/modules/misc/news.nix) but you should follow some basic guidelines: -- The entry timestamp should be in ISO-8601 format having \"+00:00\" - as time zone. For example, \"2017-09-13T17:10:14+00:00\". A suitable - timestamp can be produced by the command +- Use the included + [`create-news-entry.sh`](https://github.com/nix-community/home-manager/blob/master/modules/misc/news/create-news-entry.sh) + script to generate a news entry file: ``` shell - $ date --iso-8601=second --universal + $ modules/misc/news/create-news-entry.sh ``` + this will create a new file inside `modules/misc/news` directory + with some placeholder information that you can edit. + - The entry condition should be as specific as possible. For example, if you are changing or deprecating a specific option then you could restrict the news to those users who actually use this option. diff --git a/home-manager/build-news.nix b/home-manager/build-news.nix index 251f56ae..871423bb 100644 --- a/home-manager/build-news.nix +++ b/home-manager/build-news.nix @@ -6,8 +6,8 @@ let inherit (builtins) - concatStringsSep filter hasAttr isString length optionalString readFile - replaceStrings sort split; + concatStringsSep filter hasAttr isString length readFile replaceStrings sort + split; newsJson = builtins.fromJSON (builtins.readFile newsJsonFile); diff --git a/modules/misc/news.nix b/modules/misc/news.nix index 78a0f9a4..62b97ddf 100644 --- a/modules/misc/news.nix +++ b/modules/misc/news.nix @@ -45,6 +45,13 @@ let id = lib.mkDefault (builtins.hashString "sha256" config.message); }; }); + + isNixFile = n: v: v == "regular" && lib.hasSuffix ".nix" n; + # builtins.attrNames return the values in alphabetical order + newsFiles = + builtins.attrNames (lib.filterAttrs isNixFile (builtins.readDir ./news)); + newsEntries = + builtins.map (newsFile: import (./news + "/${newsFile}")) newsFiles; in { meta.maintainers = [ lib.maintainers.rycee ]; @@ -96,15 +103,8 @@ in { news.json.output = pkgs.writeText "hm-news.json" (builtins.toJSON { inherit (cfg) display entries; }); - # Add news entries in chronological order (i.e., latest time - # should be at the bottom of the list). The time should be - # formatted as given in the output of - # - # date --iso-8601=second --universal - # - # On darwin (or BSD like systems) use - # - # date -u +'%Y-%m-%dT%H:%M:%S+00:00' + # DO NOT define new entries here, instead use the `./create-news-entry.sh` + # script and create an individual news file inside `news` sub-directory. news.entries = [ { time = "2021-06-02T04:24:10+00:00"; @@ -2231,6 +2231,6 @@ in { See https://github.com/ivaaaan/smug for more information. ''; } - ]; + ] ++ newsEntries; }; } diff --git a/modules/misc/news/2025-04-02_13-01-34.nix b/modules/misc/news/2025-04-02_13-01-34.nix new file mode 100644 index 00000000..82ed637d --- /dev/null +++ b/modules/misc/news/2025-04-02_13-01-34.nix @@ -0,0 +1,10 @@ +{ + time = "2025-04-02T13:01:34+00:00"; + condition = true; + message = '' + A new way to define news is available. + + Instead of editing the previous news.nix file, you can now define entries + using individual files. This should reduce the number of merge conflicts. + ''; +} diff --git a/modules/misc/news/create-news-entry.sh b/modules/misc/news/create-news-entry.sh new file mode 100755 index 00000000..04d9d6ec --- /dev/null +++ b/modules/misc/news/create-news-entry.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env nix-shell +#! nix-shell -I https://github.com/NixOS/nixpkgs/archive/05f0934825c2a0750d4888c4735f9420c906b388.tar.gz -i bash -p coreutils + +DATE="$(date --iso-8601=second --universal)" +FILENAME="$(date --date="$DATE" +"%Y-%m-%d_%H-%M-%S").nix" +DIRNAME="$(dirname -- "${BASH_SOURCE[0]}")" + +cd "$DIRNAME" || { + >&2 echo "Failed to change to the script directory: $DIRNAME" + exit 1 +} + +cat - << EOF > "$FILENAME" +{ + time = "$DATE"; + condition = true; + message = '' + PLACEHOLDER + ''; +} +EOF + +echo "Successfully created a news file: $DIRNAME/$FILENAME" +echo "You can open the file above in your text editor and edit now."