From 0cf92cfa4cd4a0c156dbf3dc0e83b7274996a03b Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 20 Jun 2024 18:30:08 +0200 Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=93=9D=20Add=20comments=20to=20change?= =?UTF-8?q?=20note=20categories?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pyproject.toml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 734c508ca7..895cedb5f0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -372,42 +372,58 @@ 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" showcontent = true [[tool.towncrier.type]] +# Declarations of future API removals and breaking changes in behavior. directory = "deprecation" name = "Deprecations" showcontent = true [[tool.towncrier.type]] +# New behaviors, public APIs. That sort of stuff. directory = "feature" name = "Features" showcontent = true [[tool.towncrier.type]] +# New behaviors in existing features. directory = "improvement" name = "Improvements" 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]] +# Updates regarding bundling dependencies. directory = "vendor" name = "Vendored Libraries" showcontent = true [[tool.towncrier.type]] +# Notable updates to the documentation structure or build process. directory = "doc" name = "Improved Documentation" showcontent = true [[tool.towncrier.type]] +# Changes that might not even be worth exposing to the end users. directory = "trivial" name = "Trivial/Internal Changes" showcontent = true From 45a89ec61f9a9552236b07cde457ed38a7217e58 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 20 Jun 2024 19:17:40 +0200 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=93=9D=20Extend=20change=20log=20titl?= =?UTF-8?q?e=20meanings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This patch makes them more verbose so that they are clearer to the readers. --- pyproject.toml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 895cedb5f0..c850284f4c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -382,50 +382,50 @@ template = "changelog/_template.rst" # 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]] # Changes that might not even be worth exposing to the end users. directory = "trivial" -name = "Trivial/Internal Changes" +name = "Trivial/internal changes" showcontent = true [tool.mypy] From 03be1ed8b1794f837dddc7f26aabebe203d90bea Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 20 Jun 2024 19:35:40 +0200 Subject: [PATCH 3/5] =?UTF-8?q?=F0=9F=93=9D=F0=9F=92=85=20Split=20`trivial?= =?UTF-8?q?`=20change=20log=20category=20into=203?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new change note types are `packaging`, `contrib` and `misc`. `packaging` is intended for the audience of downstream redistributors. The `contrib` notes are meant to be documenting news affecting the project contributors, their development, and processes. Finally, `misc` is for things that don't fit anywhere but are still desired to be documented for some reason. --- .pre-commit-config.yaml | 37 +++++++++++++++++++++++++++++++++++-- changelog/README.rst | 14 +++++++++++++- pyproject.toml | 20 +++++++++++++++++--- 3 files changed, 65 insertions(+), 6 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5a3d75ff87..c85175f292 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/README.rst b/changelog/README.rst index 88956ef28d..fdaa573d42 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 c850284f4c..14f69bc342 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -423,9 +423,23 @@ name = "Improved documentation" showcontent = true [[tool.towncrier.type]] -# Changes that might not even be worth exposing to the end users. -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] From 3ce1d658bd4e952a28774525ed5235987f1883fc Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 20 Jun 2024 21:59:39 +0200 Subject: [PATCH 4/5] =?UTF-8?q?=F0=9F=8E=A8=20Set=20up=20Git=20to=20only?= =?UTF-8?q?=20allow=20certain=20change=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- changelog/.gitignore | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 changelog/.gitignore diff --git a/changelog/.gitignore b/changelog/.gitignore new file mode 100644 index 0000000000..3b34da34bc --- /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 From e73db6864208dba4e6722a208419c7fc730335d5 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 20 Jun 2024 20:06:02 +0200 Subject: [PATCH 5/5] =?UTF-8?q?=F0=9F=93=9D=20Add=20a=20change=20note=20fo?= =?UTF-8?q?r=20PR=20#12501?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- changelog/12501.contrib.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 changelog/12501.contrib.rst diff --git a/changelog/12501.contrib.rst b/changelog/12501.contrib.rst new file mode 100644 index 0000000000..6f434c287b --- /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`