Skip to content

Commit 6e5fb51

Browse files
webknjazwebknjaz
committed
📝💄 Split the "process" change log entry to 3
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
1 parent 1b8c1fd commit 6e5fb51

9 files changed

+108
-5
lines changed

‎.pre-commit-config.yaml

+38-2
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,45 @@ repos:
6565
- id: news-fragment-filenames
6666
name: NEWS fragment
6767
language: fail
68-
entry: NEWS fragment files must be named *.(process|removal|feature|bugfix|vendor|doc|trivial).rst
69-
exclude: ^news/(.gitignore|.*\.(process|removal|feature|bugfix|vendor|doc|trivial).rst)
68+
entry: >-
69+
NEWS fragment files must be named
70+
####.(
71+
removal
72+
|feature
73+
|bugfix
74+
|vendor
75+
|doc
76+
|packaging
77+
|contrib
78+
|misc
79+
|trivial
80+
)(.#)?(.rst)?
81+
exclude: >-
82+
(?x)
83+
^
84+
news/(
85+
\.gitignore
86+
|(\d+|[0-9a-f]{8}|[0-9a-f]{7}|[0-9a-f]{40}|\+[^.]+)\.(
87+
removal
88+
|feature
89+
|bugfix
90+
|vendor
91+
|doc
92+
|packaging
93+
|contrib
94+
|misc
95+
|trivial
96+
)(\.\d+)?(\.rst)?
97+
|[0-9a-zA-Z-_]+\.vendor(\.\d+)?(\.rst)? # special-case vendoring
98+
|README\.rst
99+
|\.towncrier-template\.rst\.j2
100+
)
101+
$
70102
files: ^news/
103+
types: []
104+
types_or:
105+
- file
106+
- symlink
71107

72108
ci:
73109
autofix_prs: false

‎docs/html/development/contributing.rst

+21-2
Original file line numberDiff line numberDiff line change
@@ -110,8 +110,8 @@ public is concerned, typo fixes, white space modification, etc. To mark a PR
110110
as trivial a contributor simply needs to add a randomly named, empty file to
111111
the ``news/`` directory with the extension of ``.trivial.rst``. If you are on a
112112
POSIX like operating system, one can be added by running
113-
``touch news/$(uuidgen).trivial.rst``. On Windows, the same result can be
114-
achieved in Powershell using ``New-Item "news/$([guid]::NewGuid()).trivial.rst"``.
113+
``touch news/+$(uuidgen).trivial.rst``. On Windows, the same result can be
114+
achieved in Powershell using ``New-Item "news/+$([guid]::NewGuid()).trivial.rst"``.
115115
Core committers may also add a "skip news" label to the PR which will accomplish
116116
the same thing.
117117

@@ -126,6 +126,25 @@ otherwise notable can be done using a ``news/<name>.process.rst`` file. This is
126126
not typically used, but can be used for things like changing version schemes,
127127
updating deprecation policy, etc.
128128

129+
Changes to the packaging metadata and tooling of pip itself should be documented
130+
in :file:`news/{<name>}.packaging.rst` files. This can include notes for
131+
downstreams about unobvious side effects and tooling, as well as changes in the
132+
test invocation considerations and runtime assumptions.
133+
134+
When your change is something that influence how contributors and core
135+
committers interact with the project, record that and actionable updates via a
136+
:file:`news/{<name>}.contrib.rst` file. Stuff that affects the contributor
137+
experience, like running tests, building the docs, setting up the development
138+
environment would go here. It's useful for occasional contributors to learn the
139+
gist of what's changed since the last time they were active.
140+
141+
If you feel like that your change would affect the end-users in noticeable ways
142+
but it's difficult to assign any of the above categories to it, it is possible
143+
to add a :file:`news/{<name>}.misc.rst` file to still present the change's
144+
effect in the change log. Unlike :file:`news/{<name>}.trivial.rst` entries, this
145+
change log fragment type will show up publicly in the released change log
146+
document.
147+
129148

130149
Updating your branch
131150
====================

‎news/72167f18-bd68-41e1-8404-4d23e6b2652f.trivial.rst renamed to ‎news/+72167f18-bd68-41e1-8404-4d23e6b2652f.trivial.rst

File renamed without changes.

‎news/aa82171b-1578-4128-8db3-9aa72b3a6a84.trivial.rst renamed to ‎news/+aa82171b-1578-4128-8db3-9aa72b3a6a84.trivial.rst

File renamed without changes.

‎news/d0281e66-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst renamed to ‎news/+d0281e66-f6f9-4fb6-ac44-b5a9d468d42b.trivial.rst

File renamed without changes.

‎news/.gitignore

+28
Original file line numberDiff line numberDiff line change
@@ -1 +1,29 @@
1+
*
12
!.gitignore
3+
!*.bugfix
4+
!*.bugfix.rst
5+
!*.bugfix.*.rst
6+
!*.contrib
7+
!*.contrib.rst
8+
!*.contrib.*.rst
9+
!*.doc
10+
!*.doc.rst
11+
!*.doc.*.rst
12+
!*.feature
13+
!*.feature.rst
14+
!*.feature.*.rst
15+
!*.misc
16+
!*.misc.rst
17+
!*.misc.*.rst
18+
!*.packaging
19+
!*.packaging.rst
20+
!*.packaging.*.rst
21+
!*.removal
22+
!*.removal.rst
23+
!*.removal.*.rst
24+
!*.trivial
25+
!*.trivial.rst
26+
!*.trivial.*.rst
27+
!*.trivial
28+
!*.vendor.rst
29+
!*.vendor.*.rst

‎news/12555.contrib.rst

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
12853.contrib.rst

‎news/12853.contrib.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Added separate changelog fragment types for contributor-
2+
and downstream-facing patches, as well as a catch-all
3+
miscellaneous section.
4+
5+
Their corresponding identifiers are ``contrib`` and ``packaging``
6+
respectively. They are meant to be used for more accurate
7+
classification, where one would resort to using ``misc`` otherwise.

‎pyproject.toml

+13-1
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,19 @@ type = [
9494
{ name = "Bug Fixes", directory = "bugfix", showcontent = true },
9595
{ name = "Vendored Libraries", directory = "vendor", showcontent = true },
9696
{ name = "Improved Documentation", directory = "doc", showcontent = true },
97-
{ name = "Process", directory = "process", showcontent = true },
97+
98+
# Notes for downstreams about unobvious side effects and tooling. Changes
99+
# in the test invocation considerations and runtime assumptions.
100+
{ name = "Packaging updates and notes for downstreams", directory = "packaging", showcontent = true },
101+
102+
# Stuff that affects the contributor experience. e.g. Running tests,
103+
# building the docs, setting up the development environment.
104+
{ name = "Contributor-facing changes", directory = "contrib", showcontent = true },
105+
106+
# Changes that are hard to assign to any of the above categories.
107+
{ name = "Miscellaneous internal changes", directory = "misc", showcontent = true },
108+
109+
# A way for the contributors to fool the changelog fragment presence check.
98110
{ name = "Trivial Changes", directory = "trivial", showcontent = false },
99111
]
100112

0 commit comments

Comments
 (0)