Pre-commit hook suggestions

.pre-commit-hooks.yaml

@@ -1,16 +1,27 @@
-- id: towncrier-check
-  name: towncrier-check
+- id: towncrier-draft
+  name: towncrier build --draft
   description: Check towncrier changelog updates
-  entry: towncrier --draft
+  language: python
+  entry: towncrier build --draft
   pass_filenames: false
   types: [text]
-  files: newsfragments/
+
+- id: towncrier-checks
+  name: towncrier check
+  description: Check for missing news fragments
   language: python
+  entry: towncrier check
+  pass_filenames: false
+  stages:
+    - pre-push
+  always_run: true
+
 - id: towncrier-update
-  name: towncrier-update
+  name: towncrier build
   description: Update changelog with towncrier
-  entry: towncrier
-  pass_filenames: false
-  args: ["--yes"]
-  files: newsfragments/
   language: python
+  entry: towncrier build --yes
+  pass_filenames: false
+  always_run: true
+  stages:
+    - manual

docs/pre-commit.rst

@@ -5,33 +5,67 @@ pre-commit
 
 No additional configuration is needed in your ``towncrier`` configuration; the hook will read from the appropriate configuration files in your project.
 
-
-Examples
---------
-
-Usage with the default configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 .. code-block:: yaml
 
     repos:
       - repo: https://github.com/twisted/towncrier
         rev: 23.11.0  # run 'pre-commit autoupdate' to update
         hooks:
-          - id: towncrier-check
+          - id: towncrier-checks
+
+
+``towncrier-checks`` Hook
+-------------------------
+
+The ``towncrier-checks`` hook matches the ``towncrier check`` command, useful to check that a feature branch adds at least one news fragment.
+
+This hook runs no matter which files were modified, only during the ``pre-push`` stage by default.
 
 
-Usage with custom configuration and directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``towncrier-draft`` Hook
+------------------------
 
-News fragments are stored in ``changelog.d/`` in the root of the repository and we want to keep the news fragments when running ``update``:
+The ``towncrier-draft`` hook matches the ``towncrier build --draft`` command, useful to create a draft of news fragments that will be added to the next release, ensuring they are formatted correctly.
+
+This hook runs in all stages if any text files were added or modified.
+
+If you want to limit this to only run when files change within your fragments directory, you can add ``files`` to your pre-commit configuration.
+For example, if you use the default ``newsfragments`` directory:
 
 .. code-block:: yaml
 
-    repos:
-      - repo: https://github.com/twisted/towncrier
-        rev: 23.11.0  # run 'pre-commit autoupdate' to update
-        hooks:
-          - id: towncrier-update
-            files: $changelog\.d/
-            args: ['--keep']
+    ...
+      - id: towncrier-draft
+        files: newsfragments/
+
+.. note::
+
+    The ``draft`` hook was previously (somewhat confusingly) named ``towncrier-check``.
+
+
+``towncrier-update`` Hook
+-------------------------
+
+The ``towncrier-update`` hook matches the ``towncrier build`` command, which updates the changelog to a new version containing any news fragments.
+
+It requires the version to be defined in your configuration file, or that is can be inferred from the Python package defined in your configuration file.
+It uses the ``--yes`` flag to automatically confirm the git deletion of news fragments that are added to the changelog.
+
+This hook runs no matter which files were modified, but only via the ``manual`` stage by default (meaning you run ``pre-commit run --hook-stage manual towncrier-update`` to update the changelog, or change the ``stages`` in your pre-commit configuration file).
+
+
+Customizing the hook arguments
+------------------------------
+
+You can customize the hook arguments by adding them to the ``args`` key in your pre-commit configuration file.
+
+.. code-block:: yaml
+
+  repos:
+    - repo: https://github.com/twisted/towncrier
+      rev: 23.11.0  # run 'pre-commit autoupdate' to update
+      hooks:
+      - id: towncrier-checks
+        args: ['--compare-with', 'trunk']
+      - id: towncrier-update
+        args: ['--config', 'custom.toml', '--directory', 'src/myapp']