Added pre-commit hooks for checking and updating news in projects usi…

…ng pre-commit (twisted#498) * added ``towncrier-check`` to just check newly commited news fragments * added ``towncrier-update`` to actually update the news * added documentation section for ``pre-commit``
COUR4G3 · Apr 27, 2023 · b5fe641 · b5fe641
1 parent 5c48346
commit b5fe641
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 0 deletions.
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
@@ -0,0 +1,16 @@
+- id: towncrier-check
+  name: towncrier-check
+  description: Check towncrier changelog updates
+  entry: towncrier --draft
+  pass_filenames: false
+  types: [text]
+  files: newsfragments/
+  language: python
+- id: towncrier-update
+  name: towncrier-update
+  description: Update changelog with towncrier
+  entry: towncrier
+  pass_filenames: false
+  args: ["--yes"]
+  files: newsfragments/
+  language: python
diff --git a/docs/index.rst b/docs/index.rst
@@ -23,6 +23,7 @@ Reference
 
    cli
    configuration
+   pre-commit
    customization/index
 
 

diff --git a/docs/pre-commit.rst b/docs/pre-commit.rst
@@ -0,0 +1,41 @@
+pre-commit
+==========
+
+``towncrier`` can also be used in your `pre-commit <https://pre-commit.com/>`_ configuration (``.pre-commit-config.yaml``)
+to check and/or update your news fragments on commit or during CI processes.
+
+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: 22.13.0  # run 'pre-commit autoupdate' to update
+      - hooks:
+          - id: towncrier-check
+
+
+Usage with custom configuration and directories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+News fragments are stored in ``changelog.d/`` in the root of the repository and we want to keep the news fragments when
+running ``update``:
+
+.. code-block:: yaml
+
+    repos:
+      - repo: https://github.com/twisted/towncrier
+      - rev: 22.13.0  # run 'pre-commit autoupdate' to update
+      - hooks:
+          - id: towncrier-update
+            files: $changelog\.d/
+            args: ['--keep']
+
diff --git a/src/towncrier/newsfragments/498.feature b/src/towncrier/newsfragments/498.feature
@@ -0,0 +1 @@
+Added pre-commit hooks for checking and updating news in projects using pre-commit.