From 9e6f247df4602f5e8653683feb30626ec91f7aab Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 15 Jul 2024 13:31:07 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=F0=9F=92=84=20Split=20the=20"proce?= =?UTF-8?q?ss"=20change=20log=20entry=20to=203?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, the change log had a section called "Process". And some of the incoming pull requests would add change notes there when they couldn't be put into other categories. Using it like that is not a good idea. This patch rethinks the categorization and the audiences of a few common change types and defines respective categories that replace "Process". The new categories are: * `packaging` -- news for downstream re-packagers * `contrib` -- news for regular project participants * `misc` -- public change log for things that don't fit anywhere but are useful Resolves #12555 --- .pre-commit-config.yaml | 40 ++++++++++++++++++- docs/html/development/contributing.rst | 22 +++++++++- ...8-bd68-41e1-8404-4d23e6b2652f.trivial.rst} | 0 ...b-1578-4128-8db3-9aa72b3a6a84.trivial.rst} | 0 ...6-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst} | 0 news/.gitignore | 28 +++++++++++++ news/12853.contrib.rst | 7 ++++ pyproject.toml | 14 ++++++- 8 files changed, 106 insertions(+), 5 deletions(-) rename news/{72167f18-bd68-41e1-8404-4d23e6b2652f.trivial.rst => +72167f18-bd68-41e1-8404-4d23e6b2652f.trivial.rst} (100%) rename news/{aa82171b-1578-4128-8db3-9aa72b3a6a84.trivial.rst => +aa82171b-1578-4128-8db3-9aa72b3a6a84.trivial.rst} (100%) rename news/{d0281e66-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst => +d0281e66-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst} (100%) create mode 100644 news/12853.contrib.rst diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7880e0cb409..dbae95d0ea5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -65,9 +65,45 @@ repos: - id: news-fragment-filenames name: NEWS fragment language: fail - entry: NEWS fragment files must be named *.(process|removal|feature|bugfix|vendor|doc|trivial).rst - exclude: ^news/(.gitignore|.*\.(process|removal|feature|bugfix|vendor|doc|trivial).rst) + entry: >- + NEWS fragment files must be named + ####.( + removal + |feature + |bugfix + |vendor + |doc + |packaging + |contrib + |misc + |trivial + )(.#)?(.rst)? + exclude: >- + (?x) + ^ + news/( + \.gitignore + |(\d+|[0-9a-f]{8}|[0-9a-f]{7}|[0-9a-f]{40}|\+[^.]+)\.( + removal + |feature + |bugfix + |vendor + |doc + |packaging + |contrib + |misc + |trivial + )(\.\d+)?(\.rst)? + |[0-9a-zA-Z-_]+\.vendor(\.\d+)?(\.rst)? # special-case vendoring + |README\.rst + |\.towncrier-template\.rst\.j2 + ) + $ files: ^news/ + types: [] + types_or: + - file + - symlink ci: autofix_prs: false diff --git a/docs/html/development/contributing.rst b/docs/html/development/contributing.rst index b2f6f1d1378..53d8942395b 100644 --- a/docs/html/development/contributing.rst +++ b/docs/html/development/contributing.rst @@ -110,8 +110,8 @@ public is concerned, typo fixes, white space modification, etc. To mark a PR as trivial a contributor simply needs to add a randomly named, empty file to the ``news/`` directory with the extension of ``.trivial.rst``. If you are on a POSIX like operating system, one can be added by running -``touch news/$(uuidgen).trivial.rst``. On Windows, the same result can be -achieved in Powershell using ``New-Item "news/$([guid]::NewGuid()).trivial.rst"``. +``touch news/+$(uuidgen).trivial.rst``. On Windows, the same result can be +achieved in Powershell using ``New-Item "news/+$([guid]::NewGuid()).trivial.rst"``. Core committers may also add a "skip news" label to the PR which will accomplish the same thing. @@ -126,6 +126,24 @@ otherwise notable can be done using a ``news/.process.rst`` file. This is not typically used, but can be used for things like changing version schemes, updating deprecation policy, etc. +Changes to the packaging metadata and tooling of pip itself should be documented +in :file:`news/{name}.packaging.rst` files. This can include notes for +downstreams about unobvious side effects and tooling, as well as changes in the +test invocation considerations and runtime assumptions. + +When your change is something that influence how contributors and core +committers interact with the project, record that and actionable updates via a +:file:`news/{name}.contrib.rst` file. Stuff that affects the contributor +experience, like running tests, building the docs, setting up the development +environment would go here. It's useful for occasional contributors to learn the +gist of what's changed since the last time they were active. + +If you feel like that your change would affect the end-users in noticeable ways +but it's difficult to assign any of the above categories to it, it is possible +to add a :file:`news/{name}.misc.rst` file to still present the change's effect +in the change log. Unlike :file:`news/{name}.trivial.rst` entries, this change +log fragment type will show up publicly in the released change log document. + Updating your branch ==================== diff --git a/news/72167f18-bd68-41e1-8404-4d23e6b2652f.trivial.rst b/news/+72167f18-bd68-41e1-8404-4d23e6b2652f.trivial.rst similarity index 100% rename from news/72167f18-bd68-41e1-8404-4d23e6b2652f.trivial.rst rename to news/+72167f18-bd68-41e1-8404-4d23e6b2652f.trivial.rst diff --git a/news/aa82171b-1578-4128-8db3-9aa72b3a6a84.trivial.rst b/news/+aa82171b-1578-4128-8db3-9aa72b3a6a84.trivial.rst similarity index 100% rename from news/aa82171b-1578-4128-8db3-9aa72b3a6a84.trivial.rst rename to news/+aa82171b-1578-4128-8db3-9aa72b3a6a84.trivial.rst diff --git a/news/d0281e66-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst b/news/+d0281e66-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst similarity index 100% rename from news/d0281e66-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst rename to news/+d0281e66-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst diff --git a/news/.gitignore b/news/.gitignore index f935021a8f8..9c9c922d775 100644 --- a/news/.gitignore +++ b/news/.gitignore @@ -1 +1,29 @@ +* !.gitignore +!*.bugfix +!*.bugfix.rst +!*.bugfix.*.rst +!*.contrib +!*.contrib.rst +!*.contrib.*.rst +!*.doc +!*.doc.rst +!*.doc.*.rst +!*.feature +!*.feature.rst +!*.feature.*.rst +!*.misc +!*.misc.rst +!*.misc.*.rst +!*.packaging +!*.packaging.rst +!*.packaging.*.rst +!*.removal +!*.removal.rst +!*.removal.*.rst +!*.trivial +!*.trivial.rst +!*.trivial.*.rst +!*.trivial +!*.vendor.rst +!*.vendor.*.rst diff --git a/news/12853.contrib.rst b/news/12853.contrib.rst new file mode 100644 index 00000000000..cc8b48d2c67 --- /dev/null +++ b/news/12853.contrib.rst @@ -0,0 +1,7 @@ +Added separate changelog fragment types for contributor- +and downstream-facing patches, as well as a catch-all +miscellaneous section. + +Their corresponding identifiers are ``contrib`` and ``packaging`` +respectively. They are meant to be used for more accurate +classification, where one would resort to using ``misc`` otherwise. diff --git a/pyproject.toml b/pyproject.toml index 18ef3e57108..cb59c87c239 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -94,7 +94,19 @@ type = [ { name = "Bug Fixes", directory = "bugfix", showcontent = true }, { name = "Vendored Libraries", directory = "vendor", showcontent = true }, { name = "Improved Documentation", directory = "doc", showcontent = true }, - { name = "Process", directory = "process", showcontent = true }, + + # Notes for downstreams about unobvious side effects and tooling. Changes + # in the test invocation considerations and runtime assumptions. + { name = "Packaging updates and notes for downstreams", directory = "packaging", showcontent = true }, + + # Stuff that affects the contributor experience. e.g. Running tests, + # building the docs, setting up the development environment. + { name = "Contributor-facing changes", directory = "contrib", showcontent = true }, + + # Changes that are hard to assign to any of the above categories. + { name = "Miscellaneous internal changes", directory = "misc", showcontent = true }, + + # A way for the contributors to fool the changelog fragment presence check. { name = "Trivial Changes", directory = "trivial", showcontent = false }, ]