From 0d4691bc33e7bc73e85855a8e02f74a8e5c3796a Mon Sep 17 00:00:00 2001 From: Chris Beaven Date: Fri, 24 May 2024 12:19:20 +1200 Subject: [PATCH 1/3] Pre-commit hook suggestions --- .pre-commit-hooks.yaml | 29 ++++++++++++++------ docs/pre-commit.rst | 62 ++++++++++++++++++++++++++++++------------ 2 files changed, 64 insertions(+), 27 deletions(-) diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml index 6c101c36..c9866157 100644 --- a/.pre-commit-hooks.yaml +++ b/.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 diff --git a/docs/pre-commit.rst b/docs/pre-commit.rst index ebf04b54..b040af87 100644 --- a/docs/pre-commit.rst +++ b/docs/pre-commit.rst @@ -5,33 +5,59 @@ 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. + + +``towncrier-draft`` Hook +------------------------ + +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. + +.. note:: + The ``draft`` hook was previously (somewhat confusingly) named ``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``: +``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-update - files: $changelog\.d/ - args: ['--keep'] + 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'] + From 704043fea94fdda9032b7de7c884a1a02d302b7a Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 24 May 2024 00:24:46 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/pre-commit.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/pre-commit.rst b/docs/pre-commit.rst index b040af87..743bdda2 100644 --- a/docs/pre-commit.rst +++ b/docs/pre-commit.rst @@ -60,4 +60,3 @@ You can customize the hook arguments by adding them to the ``args`` key in your args: ['--compare-with', 'trunk'] - id: towncrier-update args: ['--config', 'custom.toml', '--directory', 'src/myapp'] - From d85929b9b7351a6997e93a8536556b6691ac888e Mon Sep 17 00:00:00 2001 From: Chris Beaven Date: Fri, 24 May 2024 12:31:09 +1200 Subject: [PATCH 3/3] Add a note about limiting towncrier-draft to fragments directory --- docs/pre-commit.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/pre-commit.rst b/docs/pre-commit.rst index 743bdda2..199dad43 100644 --- a/docs/pre-commit.rst +++ b/docs/pre-commit.rst @@ -29,6 +29,15 @@ The ``towncrier-draft`` hook matches the ``towncrier build --draft`` command, us 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 + + ... + - id: towncrier-draft + files: newsfragments/ + .. note:: The ``draft`` hook was previously (somewhat confusingly) named ``towncrier-check``.