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).

Author: thiagokokada

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.

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);
 

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;
   };
 }

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.
+  '';
+}

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."