From 66eb0fc116a8ffce4810e09500d002d7b3ac254a Mon Sep 17 00:00:00 2001 From: Austin Horstman Date: Mon, 22 Jun 2026 12:30:56 -0500 Subject: [PATCH] docs: clarify new module news conditions Clarify that new-module news should remain visible to users who have not enabled the new module yet. --- docs/manual/contributing/news.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/manual/contributing/news.md b/docs/manual/contributing/news.md index adb8582cfe..1d09d639b1 100644 --- a/docs/manual/contributing/news.md +++ b/docs/manual/contributing/news.md @@ -34,11 +34,12 @@ but you should follow some basic guidelines: This will create a new file inside the `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. - Prefer a targeted condition over skipping useful news only to avoid - notifying unaffected users. +- The entry condition should be as specific as possible for changes + affecting existing functionality. 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. Prefer a targeted + condition over skipping useful news only to avoid notifying + unaffected users. - Wrap the news message so that it will fit in the typical terminal, that is, at most 80 characters wide. Ideally a bit less. @@ -64,9 +65,9 @@ but you should follow some basic guidelines: A new module is available: 'services.foo'. - Since this news is specific to the module, its condition should use - the module enable option to avoid spamming non-users of the module, - for example `condition = config.services.foo.enable;`. + Since this news announces newly available functionality, its + condition should not require `config.services.foo.enable`; otherwise + users who may want the new module will not see the news. If the module is platform specific, e.g., a service module using systemd, then a condition like @@ -75,7 +76,6 @@ but you should follow some basic guidelines: condition = hostPlatform.isLinux; ``` - should be added, either by itself for platform-scoped news or in - combination with the module enable option. Use the `create-news-entry` - generator described above to scaffold this entry as part of your - contribution. + should be added to avoid showing the news on unsupported platforms. + Use the `create-news-entry` generator described above to scaffold + this entry as part of your contribution.