Update docs to reflect scriv

lsst-sqre · Jul 19, 2023 · a6279f2 · a6279f2
1 parent 169c0de
commit a6279f2
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 22 deletions.
diff --git 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
@@ -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
@@ -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
 ------------------