From 277951fab9540fbfa1ff855a5d257d75630ba0b2 Mon Sep 17 00:00:00 2001 From: Ronny Pfannschmidt Date: Fri, 21 Jun 2024 13:50:07 +0200 Subject: [PATCH] Merge pull request #12501 from webknjaz/maintenance/changelog-categories MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 📝💅 Split trivial change log category into 3 (cherry picked from commit b08b6d122fa82994b70f5dc1437c936d0e97ada7) --- .pre-commit-config.yaml | 37 ++++++++++++++- changelog/.gitignore | 34 ++++++++++++++ changelog/12501.contrib.rst | 11 +++++ changelog/README.rst | 14 +++++- pyproject.toml | 94 ++++++++++++++++++++++++------------- 5 files changed, 155 insertions(+), 35 deletions(-) create mode 100644 changelog/.gitignore create mode 100644 changelog/12501.contrib.rst diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a80edd28cdc..f000ba0faf8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -66,8 +66,41 @@ repos: - id: changelogs-rst name: changelog filenames language: fail - entry: 'changelog files must be named ####.(breaking|bugfix|deprecation|doc|feature|improvement|trivial|vendor).rst' - exclude: changelog/(\d+\.(breaking|bugfix|deprecation|doc|feature|improvement|trivial|vendor).rst|README.rst|_template.rst) + entry: >- + changelog files must be named + ####.( + breaking + | deprecation + | feature + | improvement + | bugfix + | vendor + | doc + | packaging + | contrib + | misc + )(.#)?(.rst)? + exclude: >- + (?x) + ^ + changelog/( + \.gitignore + |\d+\.( + breaking + |deprecation + |feature + |improvement + |bugfix + |vendor + |doc + |packaging + |contrib + |misc + )(\.\d+)?(\.rst)? + |README\.rst + |_template\.rst + ) + $ files: ^changelog/ - id: py-deprecated name: py library is deprecated diff --git a/changelog/.gitignore b/changelog/.gitignore new file mode 100644 index 00000000000..3b34da34bc6 --- /dev/null +++ b/changelog/.gitignore @@ -0,0 +1,34 @@ +* +!.gitignore +!_template.rst +!README.rst +!*.bugfix +!*.bugfix.rst +!*.bugfix.*.rst +!*.breaking +!*.breaking.rst +!*.breaking.*.rst +!*.contrib +!*.contrib.rst +!*.contrib.*.rst +!*.deprecation +!*.deprecation.rst +!*.deprecation.*.rst +!*.doc +!*.doc.rst +!*.doc.*.rst +!*.feature +!*.feature.rst +!*.feature.*.rst +!*.improvement +!*.improvement.rst +!*.improvement.*.rst +!*.misc +!*.misc.rst +!*.misc.*.rst +!*.packaging +!*.packaging.rst +!*.packaging.*.rst +!*.vendor +!*.vendor.rst +!*.vendor.*.rst diff --git a/changelog/12501.contrib.rst b/changelog/12501.contrib.rst new file mode 100644 index 00000000000..6f434c287b3 --- /dev/null +++ b/changelog/12501.contrib.rst @@ -0,0 +1,11 @@ +The changelog configuration has been updated to introduce more accurate +audience-tailored categories. Previously, there was a ``trivial`` +change log fragment type with an unclear and broad meaning. It was +removed and we now have ``contrib``, ``misc`` and ``packaging`` in +place of it. + +The new change note types target the readers who are downstream +packagers and project contributors. Additionally, the miscellaneous +section is kept for unspecified updates that do not fit anywhere else. + +-- by :user:`webknjaz` diff --git a/changelog/README.rst b/changelog/README.rst index 88956ef28d8..fdaa573d427 100644 --- a/changelog/README.rst +++ b/changelog/README.rst @@ -20,10 +20,22 @@ Each file should be named like ``..rst``, where * ``deprecation``: feature deprecation. * ``breaking``: a change which may break existing suites, such as feature removal or behavior change. * ``vendor``: changes in packages vendored in pytest. -* ``trivial``: fixing a small typo or internal change that might be noteworthy. +* ``packaging``: notes for downstreams about unobvious side effects + and tooling. changes in the test invocation considerations and + runtime assumptions. +* ``contrib``: stuff that affects the contributor experience. e.g. + Running tests, building the docs, setting up the development + environment. +* ``misc``: changes that are hard to assign to any of the above + categories. So for example: ``123.feature.rst``, ``456.bugfix.rst``. +.. tip:: + + See :file:`pyproject.toml` for all available categories + (``tool.towncrier.type``). + If your PR fixes an issue, use that number here. If there is no issue, then after you submit the PR and get the PR number you can add a changelog using that instead. diff --git a/pyproject.toml b/pyproject.toml index c9001face53..7beceade7de 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -355,45 +355,75 @@ directory = "changelog/" title_format = "pytest {version} ({project_date})" template = "changelog/_template.rst" - [[tool.towncrier.type]] - directory = "breaking" - name = "Breaking Changes" - showcontent = true +# NOTE: The types are declared because: +# NOTE: - there is no mechanism to override just the value of +# NOTE: `tool.towncrier.type.misc.showcontent`; +# NOTE: - and, we want to declare extra non-default types for +# NOTE: clarity and flexibility. - [[tool.towncrier.type]] - directory = "deprecation" - name = "Deprecations" - showcontent = true +[[tool.towncrier.type]] +# When something public gets removed in a breaking way. Could be +# deprecated in an earlier release. +directory = "breaking" +name = "Removals and backward incompatible breaking changes" +showcontent = true - [[tool.towncrier.type]] - directory = "feature" - name = "Features" - showcontent = true +[[tool.towncrier.type]] +# Declarations of future API removals and breaking changes in behavior. +directory = "deprecation" +name = "Deprecations (removal in next major release)" +showcontent = true - [[tool.towncrier.type]] - directory = "improvement" - name = "Improvements" - showcontent = true +[[tool.towncrier.type]] +# New behaviors, public APIs. That sort of stuff. +directory = "feature" +name = "New features" +showcontent = true - [[tool.towncrier.type]] - directory = "bugfix" - name = "Bug Fixes" - showcontent = true +[[tool.towncrier.type]] +# New behaviors in existing features. +directory = "improvement" +name = "Improvements in existing functionality" +showcontent = true - [[tool.towncrier.type]] - directory = "vendor" - name = "Vendored Libraries" - showcontent = true +[[tool.towncrier.type]] +# Something we deemed an improper undesired behavior that got corrected +# in the release to match pre-agreed expectations. +directory = "bugfix" +name = "Bug fixes" +showcontent = true - [[tool.towncrier.type]] - directory = "doc" - name = "Improved Documentation" - showcontent = true +[[tool.towncrier.type]] +# Updates regarding bundling dependencies. +directory = "vendor" +name = "Vendored libraries" +showcontent = true - [[tool.towncrier.type]] - directory = "trivial" - name = "Trivial/Internal Changes" - showcontent = true +[[tool.towncrier.type]] +# Notable updates to the documentation structure or build process. +directory = "doc" +name = "Improved documentation" +showcontent = true + +[[tool.towncrier.type]] +# Notes for downstreams about unobvious side effects and tooling. Changes +# in the test invocation considerations and runtime assumptions. +directory = "packaging" +name = "Packaging updates and notes for downstreams" +showcontent = true + +[[tool.towncrier.type]] +# Stuff that affects the contributor experience. e.g. Running tests, +# building the docs, setting up the development environment. +directory = "contrib" +name = "Contributor-facing changes" +showcontent = true + +[[tool.towncrier.type]] +# Changes that are hard to assign to any of the above categories. +directory = "misc" +name = "Miscellaneous internal changes" +showcontent = true [tool.mypy] files = ["src", "testing", "scripts"]