diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7880e0cb409..984f63ab8fb 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -65,9 +65,44 @@ 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)? + |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..b3f9be3dfc5 100644 --- a/docs/html/development/contributing.rst +++ b/docs/html/development/contributing.rst @@ -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/.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/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 }, ]