Added pre-commit hooks (#498) (#499)

* Added pre-commit hooks for checking and updating news in projects using pre-commit (#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``

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Apply suggestions from code review

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Hynek Schlawack <[email protected]>

.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

docs/index.rst

@@ -23,6 +23,7 @@ Reference
 
    cli
    configuration
+   pre-commit
    customization/index
 
 

docs/pre-commit.rst

@@ -0,0 +1,37 @@
+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']

src/towncrier/newsfragments/498.feature

@@ -0,0 +1 @@
+Added pre-commit hooks for checking and updating news in projects using pre-commit.