Skip to content

Commit 780d0c1

Browse files
RonnyPfannschmidtRonnyPfannschmidt
authored
Merge pull request #12506 from webknjaz/backports/8.2.x/b08b6d1/pr-12501
[PR #12501/b08b6d1 backport][8.2.x] 📝💅 Split trivial change log category into 3
2 parents 76065e5 + 277951f commit 780d0c1

File tree

5 files changed

+155
-35
lines changed

5 files changed

+155
-35
lines changed

‎.pre-commit-config.yaml

+35-2
Original file line numberDiff line numberDiff line change
@@ -66,8 +66,41 @@ repos:
6666
- id: changelogs-rst
6767
name: changelog filenames
6868
language: fail
69-
entry: 'changelog files must be named ####.(breaking|bugfix|deprecation|doc|feature|improvement|trivial|vendor).rst'
70-
exclude: changelog/(\d+\.(breaking|bugfix|deprecation|doc|feature|improvement|trivial|vendor).rst|README.rst|_template.rst)
69+
entry: >-
70+
changelog files must be named
71+
####.(
72+
breaking
73+
| deprecation
74+
| feature
75+
| improvement
76+
| bugfix
77+
| vendor
78+
| doc
79+
| packaging
80+
| contrib
81+
| misc
82+
)(.#)?(.rst)?
83+
exclude: >-
84+
(?x)
85+
^
86+
changelog/(
87+
\.gitignore
88+
|\d+\.(
89+
breaking
90+
|deprecation
91+
|feature
92+
|improvement
93+
|bugfix
94+
|vendor
95+
|doc
96+
|packaging
97+
|contrib
98+
|misc
99+
)(\.\d+)?(\.rst)?
100+
|README\.rst
101+
|_template\.rst
102+
)
103+
$
71104
files: ^changelog/
72105
- id: py-deprecated
73106
name: py library is deprecated

‎changelog/.gitignore

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
*
2+
!.gitignore
3+
!_template.rst
4+
!README.rst
5+
!*.bugfix
6+
!*.bugfix.rst
7+
!*.bugfix.*.rst
8+
!*.breaking
9+
!*.breaking.rst
10+
!*.breaking.*.rst
11+
!*.contrib
12+
!*.contrib.rst
13+
!*.contrib.*.rst
14+
!*.deprecation
15+
!*.deprecation.rst
16+
!*.deprecation.*.rst
17+
!*.doc
18+
!*.doc.rst
19+
!*.doc.*.rst
20+
!*.feature
21+
!*.feature.rst
22+
!*.feature.*.rst
23+
!*.improvement
24+
!*.improvement.rst
25+
!*.improvement.*.rst
26+
!*.misc
27+
!*.misc.rst
28+
!*.misc.*.rst
29+
!*.packaging
30+
!*.packaging.rst
31+
!*.packaging.*.rst
32+
!*.vendor
33+
!*.vendor.rst
34+
!*.vendor.*.rst

‎changelog/12501.contrib.rst

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
The changelog configuration has been updated to introduce more accurate
2+
audience-tailored categories. Previously, there was a ``trivial``
3+
change log fragment type with an unclear and broad meaning. It was
4+
removed and we now have ``contrib``, ``misc`` and ``packaging`` in
5+
place of it.
6+
7+
The new change note types target the readers who are downstream
8+
packagers and project contributors. Additionally, the miscellaneous
9+
section is kept for unspecified updates that do not fit anywhere else.
10+
11+
-- by :user:`webknjaz`

‎changelog/README.rst

+13-1
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,22 @@ Each file should be named like ``<ISSUE>.<TYPE>.rst``, where
2020
* ``deprecation``: feature deprecation.
2121
* ``breaking``: a change which may break existing suites, such as feature removal or behavior change.
2222
* ``vendor``: changes in packages vendored in pytest.
23-
* ``trivial``: fixing a small typo or internal change that might be noteworthy.
23+
* ``packaging``: notes for downstreams about unobvious side effects
24+
and tooling. changes in the test invocation considerations and
25+
runtime assumptions.
26+
* ``contrib``: stuff that affects the contributor experience. e.g.
27+
Running tests, building the docs, setting up the development
28+
environment.
29+
* ``misc``: changes that are hard to assign to any of the above
30+
categories.
2431

2532
So for example: ``123.feature.rst``, ``456.bugfix.rst``.
2633

34+
.. tip::
35+
36+
See :file:`pyproject.toml` for all available categories
37+
(``tool.towncrier.type``).
38+
2739
If your PR fixes an issue, use that number here. If there is no issue,
2840
then after you submit the PR and get the PR number you can add a
2941
changelog using that instead.

‎pyproject.toml

+62-32
Original file line numberDiff line numberDiff line change
@@ -355,45 +355,75 @@ directory = "changelog/"
355355
title_format = "pytest {version} ({project_date})"
356356
template = "changelog/_template.rst"
357357

358-
[[tool.towncrier.type]]
359-
directory = "breaking"
360-
name = "Breaking Changes"
361-
showcontent = true
358+
# NOTE: The types are declared because:
359+
# NOTE: - there is no mechanism to override just the value of
360+
# NOTE: `tool.towncrier.type.misc.showcontent`;
361+
# NOTE: - and, we want to declare extra non-default types for
362+
# NOTE: clarity and flexibility.
362363

363-
[[tool.towncrier.type]]
364-
directory = "deprecation"
365-
name = "Deprecations"
366-
showcontent = true
364+
[[tool.towncrier.type]]
365+
# When something public gets removed in a breaking way. Could be
366+
# deprecated in an earlier release.
367+
directory = "breaking"
368+
name = "Removals and backward incompatible breaking changes"
369+
showcontent = true
367370

368-
[[tool.towncrier.type]]
369-
directory = "feature"
370-
name = "Features"
371-
showcontent = true
371+
[[tool.towncrier.type]]
372+
# Declarations of future API removals and breaking changes in behavior.
373+
directory = "deprecation"
374+
name = "Deprecations (removal in next major release)"
375+
showcontent = true
372376

373-
[[tool.towncrier.type]]
374-
directory = "improvement"
375-
name = "Improvements"
376-
showcontent = true
377+
[[tool.towncrier.type]]
378+
# New behaviors, public APIs. That sort of stuff.
379+
directory = "feature"
380+
name = "New features"
381+
showcontent = true
377382

378-
[[tool.towncrier.type]]
379-
directory = "bugfix"
380-
name = "Bug Fixes"
381-
showcontent = true
383+
[[tool.towncrier.type]]
384+
# New behaviors in existing features.
385+
directory = "improvement"
386+
name = "Improvements in existing functionality"
387+
showcontent = true
382388

383-
[[tool.towncrier.type]]
384-
directory = "vendor"
385-
name = "Vendored Libraries"
386-
showcontent = true
389+
[[tool.towncrier.type]]
390+
# Something we deemed an improper undesired behavior that got corrected
391+
# in the release to match pre-agreed expectations.
392+
directory = "bugfix"
393+
name = "Bug fixes"
394+
showcontent = true
387395

388-
[[tool.towncrier.type]]
389-
directory = "doc"
390-
name = "Improved Documentation"
391-
showcontent = true
396+
[[tool.towncrier.type]]
397+
# Updates regarding bundling dependencies.
398+
directory = "vendor"
399+
name = "Vendored libraries"
400+
showcontent = true
392401

393-
[[tool.towncrier.type]]
394-
directory = "trivial"
395-
name = "Trivial/Internal Changes"
396-
showcontent = true
402+
[[tool.towncrier.type]]
403+
# Notable updates to the documentation structure or build process.
404+
directory = "doc"
405+
name = "Improved documentation"
406+
showcontent = true
407+
408+
[[tool.towncrier.type]]
409+
# Notes for downstreams about unobvious side effects and tooling. Changes
410+
# in the test invocation considerations and runtime assumptions.
411+
directory = "packaging"
412+
name = "Packaging updates and notes for downstreams"
413+
showcontent = true
414+
415+
[[tool.towncrier.type]]
416+
# Stuff that affects the contributor experience. e.g. Running tests,
417+
# building the docs, setting up the development environment.
418+
directory = "contrib"
419+
name = "Contributor-facing changes"
420+
showcontent = true
421+
422+
[[tool.towncrier.type]]
423+
# Changes that are hard to assign to any of the above categories.
424+
directory = "misc"
425+
name = "Miscellaneous internal changes"
426+
showcontent = true
397427

398428
[tool.mypy]
399429
files = ["src", "testing", "scripts"]

0 commit comments

Comments
 (0)