From a6279f224384a13cd55d42da562d3f7bfe817a65 Mon Sep 17 00:00:00 2001
From: Jonathan Sick <jsick@lsst.org>
Date: Tue, 18 Jul 2023 18:03:01 -0400
Subject: [PATCH] Update docs to reflect scriv

---
 docs/_rst_epilog.rst     |  1 +
 docs/dev/development.rst | 26 +++++++-------------------
 docs/dev/release.rst     | 11 ++++++++---
 3 files changed, 16 insertions(+), 22 deletions(-)

diff --git a/docs/_rst_epilog.rst b/docs/_rst_epilog.rst
index 828e6bf..e8735b0 100644
--- a/docs/_rst_epilog.rst
+++ b/docs/_rst_epilog.rst
@@ -10,3 +10,4 @@
 .. _Schema Evolution and Compatibility: https://docs.confluent.io/current/schema-registry/avro.html
 .. _Strimzi: https://strimzi.io
 .. _tox: https://tox.readthedocs.io/en/latest/
+.. _scriv: https://scriv.readthedocs.io/en/latest/
diff --git a/docs/dev/development.rst b/docs/dev/development.rst
index 15a68ae..9413768 100644
--- a/docs/dev/development.rst
+++ b/docs/dev/development.rst
@@ -99,29 +99,17 @@ Updating the change log
 =======================
 
 Each pull request should update the change log (:file:`CHANGELOG.md`).
-Add a description of new features and fixes as list items under a section at the top of the change log called "Unreleased:"
+The change log is maintained with scriv_.
 
-.. code-block:: md
+To create a new change log fragment, run:
 
-   ## Unreleased
-
-   - Description of the feature or fix.
-
-If the next version is known (because Kafkit's main branch is being prepared for a new major or minor version), the section may contain that version information:
-
-.. code-block:: md
-
-   ## X.Y.0 (unreleased)
-
-   - Description of the feature or fix.
-
-If the exact version and release date is known (:doc:`because a release is being prepared <release>`), the section header is formatted as:
-
-.. code-block:: rst
+.. code-block:: sh
 
-   ## X.Y.0 (YYYY-MM-DD)
+   scriv create
 
-   - Description of the feature or fix.
+This creates a new file in the :file:`changelog.d` directory.
+Edit this file to describe the changes in the pull request.
+If sections don't apply to the change you can delete them.
 
 .. _style-guide:
 
diff --git a/docs/dev/release.rst b/docs/dev/release.rst
index abf4b73..4cdff44 100644
--- a/docs/dev/release.rst
+++ b/docs/dev/release.rst
@@ -26,11 +26,16 @@ Release tags are semantic version identifiers following the :pep:`440` specifica
 1. Change log and documentation
 -------------------------------
 
-Each PR should include updates to the change log.
+Each PR should include updates to the change log as scriv_ fragments (see :ref:`dev-change-log`).
+When a release is being made, collect these fragments into the change log by running:
+
+.. code-block:: sh
+
+   scriv collect --version "X.Y.Z"
+
 If the change log or documentation needs additional updates, now is the time to make those changes through the regular branch-and-PR development method against the ``main`` branch.
 
-In particular, replace the "Unreleased" section headline with the semantic version and date.
-See :ref:`dev-change-log` in the *Developer guide* for details.
+Each PR should have already created scriv_ change log fragments.
 
 2. Tag the release
 ------------------