From bb68a1a2e773050d64b18f5b23811c8f212c46c8 Mon Sep 17 00:00:00 2001 From: Austin Horstman Date: Tue, 9 Jun 2026 22:48:56 -0500 Subject: [PATCH] docs: add release notes contributing guidance --- docs/manual/contributing.md | 1 + docs/manual/contributing/guidelines.md | 7 +++++++ docs/manual/contributing/news.md | 11 +++++++++++ docs/manual/contributing/release-notes.md | 24 +++++++++++++++++++++++ docs/release-notes/release-notes.md | 4 ++-- 5 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 docs/manual/contributing/release-notes.md diff --git a/docs/manual/contributing.md b/docs/manual/contributing.md index 54b5dac5d..73cf8a6d1 100644 --- a/docs/manual/contributing.md +++ b/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 ``` diff --git a/docs/manual/contributing/guidelines.md b/docs/manual/contributing/guidelines.md index df93b0b38..a07eacf07 100644 --- a/docs/manual/contributing/guidelines.md +++ b/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 diff --git a/docs/manual/contributing/news.md b/docs/manual/contributing/news.md index 345956410..e00635494 100644 --- a/docs/manual/contributing/news.md +++ b/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. diff --git a/docs/manual/contributing/release-notes.md b/docs/manual/contributing/release-notes.md new file mode 100644 index 000000000..5e0d7bbef --- /dev/null +++ b/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. diff --git a/docs/release-notes/release-notes.md b/docs/release-notes/release-notes.md index 83087f537..5f7e78697 100644 --- a/docs/release-notes/release-notes.md +++ b/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