From 18cb5f888b03ca6d2d49addec763eea718399fef Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan <ncoghlan@gmail.com>
Date: Wed, 30 Oct 2024 20:51:23 +1000
Subject: [PATCH] docs: clarify how to use top-level notes

Update new_fragment.md.j2

Update new_fragment.rst.j2

Update concepts.rst

Update new_fragment.rst.j2
---
 docs/concepts.rst                       | 5 ++++-
 src/scriv/templates/new_fragment.md.j2  | 1 +
 src/scriv/templates/new_fragment.rst.j2 | 3 ++-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/docs/concepts.rst b/docs/concepts.rst
index c5d5072..aca15c3 100644
--- a/docs/concepts.rst
+++ b/docs/concepts.rst
@@ -29,8 +29,11 @@ fragment, you provide your change information in the appropriate category.
 When the fragments are collected, they are grouped by category into a single
 changelog entry.
 
+Any fragments that do not specify a category are included as top-level
+release notes directly under the release heading.
+
 You can choose not to use categories by setting the :ref:`config_categories`
-setting to empty.
+setting to empty (all notes will appear as top-level release notes).
 
 
 .. _entries:
diff --git a/src/scriv/templates/new_fragment.md.j2 b/src/scriv/templates/new_fragment.md.j2
index 3ed2ba1..c6ef1ff 100644
--- a/src/scriv/templates/new_fragment.md.j2
+++ b/src/scriv/templates/new_fragment.md.j2
@@ -2,6 +2,7 @@
 A new scriv changelog fragment.
 
 Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
 -->
 
 {% for cat in config.categories -%}
diff --git a/src/scriv/templates/new_fragment.rst.j2 b/src/scriv/templates/new_fragment.rst.j2
index c6bf798..6159b62 100644
--- a/src/scriv/templates/new_fragment.rst.j2
+++ b/src/scriv/templates/new_fragment.rst.j2
@@ -1,7 +1,8 @@
 .. A new scriv changelog fragment.
 {% if config.categories -%}
 ..
-.. Uncomment the header that is right (remove the leading dots).
+.. Uncomment the section that is right (remove the leading dots).
+.. For top level release notes, leave all the headers commented out.
 ..
 {% for cat in config.categories -%}
 .. {{ cat }}