docs: add release notes contributing guidance

docs/manual/contributing.md

@@ -22,6 +22,7 @@ configuration.
 ```{=include=} sections
 contributing/getting-started.md
 contributing/guidelines.md
+contributing/release-notes.md
 contributing/news.md
 contributing/tests.md
 ```

docs/manual/contributing/guidelines.md

@@ -159,6 +159,13 @@ formatted as described in [News](#sec-news).
 
 When new modules are added a news entry should be included.
 
+News entries and release notes serve different purposes. Release notes
+should be updated separately when a change affects users migrating
+between stable releases, such as state version default changes, required
+migration steps, or broad behavior changes. See
+[Release Notes](#sec-contributing-release-notes) and [News](#sec-news)
+for more details.
+
 ## Use conditional modules and news {#sec-guidelines-conditional-modules}
 
 Home Manager includes a number of modules that are only usable on some

docs/manual/contributing/news.md

@@ -6,6 +6,15 @@ associated news entry. In general, a news entry should only be added for
 truly noteworthy news. For example, a bug fix or new option does
 generally not need a news entry.
 
+Release notes and news entries serve different purposes. A news entry is
+shown during Home Manager activation and is useful for day-to-day
+communication about noteworthy changes, such as a new module, a new
+feature, or a specific deprecation. Release notes are read from the
+website documentation and should summarize what users need to know before
+or during a stable-release upgrade. See
+[Release Notes](#sec-contributing-release-notes) for guidance on changes
+that affect stable-release upgrades.
+
 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:
@@ -28,6 +37,8 @@ but you should follow some basic guidelines:
 -   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.
 
 -   Wrap the news message so that it will fit in the typical terminal,
     that is, at most 80 characters wide. Ideally a bit less.

docs/manual/contributing/release-notes.md

@@ -0,0 +1,24 @@
+# Release Notes {#sec-contributing-release-notes}
+
+Home Manager release notes are published as part of the website documentation in
+`docs/release-notes/rl-*.md`. They are intended for users migrating from one
+stable release to another.
+
+A change should be mentioned in the release notes when it affects migration
+between stable releases. This includes changes that require user action or
+awareness during an upgrade, such as:
+
+- breaking changes;
+- default changes guarded by `home.stateVersion`;
+- required migration steps;
+- broad behavior changes across platform or integration boundaries;
+- compatibility changes that can affect existing configurations.
+
+Do not use the presence or absence of a news entry to decide whether a change
+belongs in the release notes. A change can require a news entry, a release note,
+both, or neither.
+
+When preparing a release, review the commits since the previous stable release
+and update the upcoming release note file with the migration impact. Prefer
+concise user-facing descriptions that name the affected option paths and explain
+required action.

docs/release-notes/release-notes.md

@@ -1,7 +1,7 @@
 # Release Notes {#ch-release-notes}
 
-This section lists the release notes for stable versions of Home Manager
-and the current unstable version.
+This section lists the release notes for stable versions of Home Manager and the
+current unstable version.
 
 ```{=include=} chapters
 rl-2611.md