Skip to content

Commit b08b6d1

Browse files
RonnyPfannschmidtRonnyPfannschmidt
authored
Merge pull request #12501 from webknjaz/maintenance/changelog-categories
📝💅 Split trivial change log category into 3
2 parents bbe6b4a + e73db68 commit b08b6d1

5 files changed

Lines changed: 132 additions & 12 deletions

File tree

‎.pre-commit-config.yaml‎

Lines changed: 35 additions & 2 deletions
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‎

Lines changed: 34 additions & 0 deletions
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‎

Lines changed: 11 additions & 0 deletions
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‎

Lines changed: 13 additions & 1 deletion
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‎

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -372,44 +372,74 @@ directory = "changelog/"
372372
title_format = "pytest {version} ({project_date})"
373373
template = "changelog/_template.rst"
374374

375+
# NOTE: The types are declared because:
376+
# NOTE: - there is no mechanism to override just the value of
377+
# NOTE: `tool.towncrier.type.misc.showcontent`;
378+
# NOTE: - and, we want to declare extra non-default types for
379+
# NOTE: clarity and flexibility.
380+
375381
[[tool.towncrier.type]]
382+
# When something public gets removed in a breaking way. Could be
383+
# deprecated in an earlier release.
376384
directory = "breaking"
377-
name = "Breaking Changes"
385+
name = "Removals and backward incompatible breaking changes"
378386
showcontent = true
379387

380388
[[tool.towncrier.type]]
389+
# Declarations of future API removals and breaking changes in behavior.
381390
directory = "deprecation"
382-
name = "Deprecations"
391+
name = "Deprecations (removal in next major release)"
383392
showcontent = true
384393

385394
[[tool.towncrier.type]]
395+
# New behaviors, public APIs. That sort of stuff.
386396
directory = "feature"
387-
name = "Features"
397+
name = "New features"
388398
showcontent = true
389399

390400
[[tool.towncrier.type]]
401+
# New behaviors in existing features.
391402
directory = "improvement"
392-
name = "Improvements"
403+
name = "Improvements in existing functionality"
393404
showcontent = true
394405

395406
[[tool.towncrier.type]]
407+
# Something we deemed an improper undesired behavior that got corrected
408+
# in the release to match pre-agreed expectations.
396409
directory = "bugfix"
397-
name = "Bug Fixes"
410+
name = "Bug fixes"
398411
showcontent = true
399412

400413
[[tool.towncrier.type]]
414+
# Updates regarding bundling dependencies.
401415
directory = "vendor"
402-
name = "Vendored Libraries"
416+
name = "Vendored libraries"
403417
showcontent = true
404418

405419
[[tool.towncrier.type]]
420+
# Notable updates to the documentation structure or build process.
406421
directory = "doc"
407-
name = "Improved Documentation"
422+
name = "Improved documentation"
423+
showcontent = true
424+
425+
[[tool.towncrier.type]]
426+
# Notes for downstreams about unobvious side effects and tooling. Changes
427+
# in the test invocation considerations and runtime assumptions.
428+
directory = "packaging"
429+
name = "Packaging updates and notes for downstreams"
430+
showcontent = true
431+
432+
[[tool.towncrier.type]]
433+
# Stuff that affects the contributor experience. e.g. Running tests,
434+
# building the docs, setting up the development environment.
435+
directory = "contrib"
436+
name = "Contributor-facing changes"
408437
showcontent = true
409438

410439
[[tool.towncrier.type]]
411-
directory = "trivial"
412-
name = "Trivial/Internal Changes"
440+
# Changes that are hard to assign to any of the above categories.
441+
directory = "misc"
442+
name = "Miscellaneous internal changes"
413443
showcontent = true
414444

415445
[tool.mypy]

0 commit comments

Comments
 (0)