diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5a3d75ff8..c85175f29 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 000000000..3b34da34b --- /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 000000000..6f434c287 --- /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 88956ef28..fdaa573d4 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 734c508ca..14f69bc34 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -372,44 +372,74 @@ directory = "changelog/" title_format = "pytest {version} ({project_date})" template = "changelog/_template.rst" +# 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]] +# When something public gets removed in a breaking way. Could be +# deprecated in an earlier release. directory = "breaking" -name = "Breaking Changes" +name = "Removals and backward incompatible breaking changes" showcontent = true [[tool.towncrier.type]] +# Declarations of future API removals and breaking changes in behavior. directory = "deprecation" -name = "Deprecations" +name = "Deprecations (removal in next major release)" showcontent = true [[tool.towncrier.type]] +# New behaviors, public APIs. That sort of stuff. directory = "feature" -name = "Features" +name = "New features" showcontent = true [[tool.towncrier.type]] +# New behaviors in existing features. directory = "improvement" -name = "Improvements" +name = "Improvements in existing functionality" 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" +name = "Bug fixes" showcontent = true [[tool.towncrier.type]] +# Updates regarding bundling dependencies. directory = "vendor" -name = "Vendored Libraries" +name = "Vendored libraries" showcontent = true [[tool.towncrier.type]] +# Notable updates to the documentation structure or build process. directory = "doc" -name = "Improved Documentation" +name = "Improved documentation" showcontent = true [[tool.towncrier.type]] -directory = "trivial" -name = "Trivial/Internal Changes" +# 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]