From 3303cd1ce4fa3a0b4fb6f4c300408ba523a6bb52 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 15 Jul 2024 12:19:18 +0200 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=A4=96=20Reflow=20Towncrier=20categor?= =?UTF-8?q?ies=20list=20in=20config?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is a preparatory step for further adding of new changelog fragment types. --- pyproject.toml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index cf098eea061..18ef3e57108 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -89,13 +89,13 @@ template = "tools/news/template.rst" # Grouping of entries, within our changelog type = [ - { name = "Deprecations and Removals", directory = "removal", showcontent = true }, - { name = "Features", directory = "feature", showcontent = true }, - { 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 }, - { name = "Trivial Changes", directory = "trivial", showcontent = false }, + { name = "Deprecations and Removals", directory = "removal", showcontent = true }, + { name = "Features", directory = "feature", showcontent = true }, + { 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 }, + { name = "Trivial Changes", directory = "trivial", showcontent = false }, ] ###################################################################################### From 1b8c1fd0796d24aabde8b2d3aa77944d1f1d4224 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 15 Jul 2024 12:38:42 +0200 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=92=85=20Blame-ignore=203303cd1ce?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Said commit is a formatting change. --- .git-blame-ignore-revs | 1 + 1 file changed, 1 insertion(+) diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs index f09b08660e7..0930e126774 100644 --- a/.git-blame-ignore-revs +++ b/.git-blame-ignore-revs @@ -34,3 +34,4 @@ c7ee560e00b85f7486b452c14ff49e4737996eda # Blacken tools/ 94999255d5ede440c37137d210666fdf64302e75 # Reformat the codebase, with black 585037a80a1177f1fa92e159a7079855782e543e # Cleanup implicit string concatenation 8a6f6ac19b80a6dc35900a47016c851d9fcd2ee2 # Blacken src/pip/_internal/resolution directory +3303cd1ce4fa3a0b4fb6f4c300408ba523a6bb52 # 🤖 Reflow Towncrier categories list in config From 6e5fb5133503750e3915bc2c4bc11a7d7ce81aa3 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 15 Jul 2024 13:31:07 +0200 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=93=9D=F0=9F=92=84=20Split=20the=20"p?= =?UTF-8?q?rocess"=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 | 23 ++++++++++- ...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/12555.contrib.rst | 1 + news/12853.contrib.rst | 7 ++++ pyproject.toml | 14 ++++++- 9 files changed, 108 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 120000 news/12555.contrib.rst 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..e4a24fe8ec8 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,25 @@ 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/{}.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/{}.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/{}.misc.rst` file to still present the change's +effect in the change log. Unlike :file:`news/{}.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/12555.contrib.rst b/news/12555.contrib.rst new file mode 120000 index 00000000000..356e25c4f5c --- /dev/null +++ b/news/12555.contrib.rst @@ -0,0 +1 @@ +12853.contrib.rst \ No newline at end of file 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 }, ] From 508083b9d9c2e2f1131821fbb540645fb9b4d24a Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 15 Jul 2024 23:56:19 +0200 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=A7=AA=F0=9F=8E=A8=20Enforce=20empty?= =?UTF-8?q?=20trivial=20change=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is what the contribution document is asking for but the automation never checked really. Which led to contributors filling out trivial changelog entries without realizing that they are never published. The patch corrects that and relocates the violating change notes to better sections. --- .pre-commit-config.yaml | 28 +++++++++++++++++++ news/12660.trivial.rst | 2 -- news/{12776.trivial.rst => 12776.contrib.rst} | 0 news/{12805.trivial.rst => 12805.contrib.rst} | 0 news/12854.contrib.rst | 2 ++ news/setuptools.vendor.rst | 3 ++ 6 files changed, 33 insertions(+), 2 deletions(-) delete mode 100644 news/12660.trivial.rst rename news/{12776.trivial.rst => 12776.contrib.rst} (100%) rename news/{12805.trivial.rst => 12805.contrib.rst} (100%) create mode 100644 news/12854.contrib.rst diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dbae95d0ea5..160b260e4a7 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -104,6 +104,34 @@ repos: types_or: - file - symlink + - id: trivial-news-fragment-empty + name: Trivial NEWS fragments must be empty + language: python + entry: >- + python3 -Ic 'import pathlib, sys; + trivial_notes = map(pathlib.Path, sys.argv[1:]); + + non_empty_notes = [ + note for note in trivial_notes + if note.lstat().st_size + ]; + some_notes_are_non_empty = bool(len(non_empty_notes)); + + some_notes_are_non_empty or sys.exit(0); + + print(f"ERROR: the following change log fragments must be empty:"); + + print("\n\t* ".join(["", *map(str, non_empty_notes)])); + + print(); + + sys.exit(1) + ' + files: ^news/[^.]+\.trivial.*$ + types: [] + types_or: + - file + - symlink ci: autofix_prs: false diff --git a/news/12660.trivial.rst b/news/12660.trivial.rst deleted file mode 100644 index f02256eccbb..00000000000 --- a/news/12660.trivial.rst +++ /dev/null @@ -1,2 +0,0 @@ -Remove (suppressed) deprecation warning from vendored ``pkg_resources`` -to ensure builds succeed with ``PYTHONWARNINGS=error``. diff --git a/news/12776.trivial.rst b/news/12776.contrib.rst similarity index 100% rename from news/12776.trivial.rst rename to news/12776.contrib.rst diff --git a/news/12805.trivial.rst b/news/12805.contrib.rst similarity index 100% rename from news/12805.trivial.rst rename to news/12805.contrib.rst diff --git a/news/12854.contrib.rst b/news/12854.contrib.rst new file mode 100644 index 00000000000..33a0a798017 --- /dev/null +++ b/news/12854.contrib.rst @@ -0,0 +1,2 @@ +The pre-commit linting suite now makes sure that any change +notes labeled as ``trivial`` are empty. diff --git a/news/setuptools.vendor.rst b/news/setuptools.vendor.rst index afdd14c09dc..22676e6c213 100644 --- a/news/setuptools.vendor.rst +++ b/news/setuptools.vendor.rst @@ -1 +1,4 @@ Upgrade setuptools to 70.3.0 + +Additionally, remove the suppressed deprecation warning from the vendored +``pkg_resources`` copy to ensure builds succeed with ``PYTHONWARNINGS=error``.