Skip to content

Commit 419d715

Browse files
webknjazwebknjaz
authored
[PR #8066/cba34699 backport][3.9] 💅📝 Restructure the changelog for clarity (#8068)
**This is a backport of PR #8066 as merged into master (cba3469).** PR #8066 (cherry picked from commit cba3469) <!-- Thank you for your contribution! --> ## What do these changes do? <!-- Please give a short brief about these changes. --> ## Are there changes in behavior for the user? <!-- Outline any notable behaviour for the end users. --> ## Related issue number <!-- Are there any issues opened that will be resolved by merging this change? --> <!-- Remember to prefix with 'Fixes' if it should close the issue (e.g. 'Fixes #123'). --> ## Checklist - [ ] I think the code is well written - [ ] Unit tests for the changes exist - [ ] Documentation reflects the changes - [ ] If you provide code modification, please add yourself to `CONTRIBUTORS.txt` * The format is &lt;Name&gt; &lt;Surname&gt;. * Please keep alphabetical order, the file is sorted by names. - [ ] Add a new news fragment into the `CHANGES/` folder * name it `<issue_or_pr_num>.<type>.rst` (e.g. `588.bugfix.rst`) * if you don't have an issue number, change it to the pull request number after creating the PR * `.bugfix`: A bug fix for something the maintainers deemed an improper undesired behavior that got corrected to match pre-agreed expectations. * `.feature`: A new behavior, public APIs. That sort of stuff. * `.deprecation`: A declaration of future API removals and breaking changes in behavior. * `.breaking`: When something public is removed in a breaking way. Could be deprecated in an earlier release. * `.doc`: Notable updates to the documentation structure or build process. * `.packaging`: Notes for downstreams about unobvious side effects and tooling. Changes in the test invocation considerations and runtime assumptions. * `.contrib`: Stuff that affects the contributor experience. e.g. Running tests, building the docs, setting up the development environment. * `.misc`: Changes that are hard to assign to any of the above categories. * Make sure to use full sentences with correct case and punctuation, for example: ```rst Fixed issue with non-ascii contents in doctest text files -- by :user:`contributor-gh-handle`. ``` Use the past tense or the present tense a non-imperative mood, referring to what's changed compared to the last released version of this project.
1 parent a54dab3 commit 419d715

12 files changed

+289
-36
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md

+32-10
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,35 @@
2121
- [ ] If you provide code modification, please add yourself to `CONTRIBUTORS.txt`
2222
* The format is &lt;Name&gt; &lt;Surname&gt;.
2323
* Please keep alphabetical order, the file is sorted by names.
24-
- [ ] Add a new news fragment into the `CHANGES` folder
25-
* name it `<issue_id>.<type>` for example (588.bugfix)
26-
* if you don't have an `issue_id` change it to the pr id after creating the pr
27-
* ensure type is one of the following:
28-
* `.feature`: Signifying a new feature.
29-
* `.bugfix`: Signifying a bug fix.
30-
* `.doc`: Signifying a documentation improvement.
31-
* `.removal`: Signifying a deprecation or removal of public API.
32-
* `.misc`: A ticket has been closed, but it is not of interest to users.
33-
* Make sure to use full sentences with correct case and punctuation, for example: "Fix issue with non-ascii contents in doctest text files."
24+
- [ ] Add a new news fragment into the `CHANGES/` folder
25+
* name it `<issue_or_pr_num>.<type>.rst` (e.g. `588.bugfix.rst`)
26+
* if you don't have an issue number, change it to the pull request
27+
number after creating the PR
28+
* `.bugfix`: A bug fix for something the maintainers deemed an
29+
improper undesired behavior that got corrected to match
30+
pre-agreed expectations.
31+
* `.feature`: A new behavior, public APIs. That sort of stuff.
32+
* `.deprecation`: A declaration of future API removals and breaking
33+
changes in behavior.
34+
* `.breaking`: When something public is removed in a breaking way.
35+
Could be deprecated in an earlier release.
36+
* `.doc`: Notable updates to the documentation structure or build
37+
process.
38+
* `.packaging`: Notes for downstreams about unobvious side effects
39+
and tooling. Changes in the test invocation considerations and
40+
runtime assumptions.
41+
* `.contrib`: Stuff that affects the contributor experience. e.g.
42+
Running tests, building the docs, setting up the development
43+
environment.
44+
* `.misc`: Changes that are hard to assign to any of the above
45+
categories.
46+
* Make sure to use full sentences with correct case and punctuation,
47+
for example:
48+
```rst
49+
Fixed issue with non-ascii contents in doctest text files
50+
-- by :user:`contributor-gh-handle`.
51+
```
52+
53+
Use the past tense or the present tense a non-imperative mood,
54+
referring to what's changed compared to the last released version
55+
of this project.

‎.github/workflows/ci-cd.yml

+4-2
Original file line numberDiff line numberDiff line change
@@ -414,8 +414,10 @@ jobs:
414414
version_file: aiohttp/__init__.py
415415
github_token: ${{ secrets.GITHUB_TOKEN }}
416416
dist_dir: dist
417-
fix_issue_regex: "`#(\\d+) <https://github.com/aio-libs/aiohttp/issues/\\1>`_"
418-
fix_issue_repl: "(#\\1)"
417+
fix_issue_regex: >-
418+
:issue:`(\d+)`
419+
fix_issue_repl: >-
420+
#\1
419421
420422
- name: >-
421423
Publish 🐍📦 to PyPI

‎.pre-commit-config.yaml

+28-2
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,35 @@ repos:
66
language: fail
77
entry: >-
88
Changelog files must be named
9-
####.(bugfix|feature|removal|doc|misc)(.#)?(.rst)?
9+
####.(
10+
bugfix
11+
| feature
12+
| deprecation
13+
| breaking
14+
| doc
15+
| packaging
16+
| contrib
17+
| misc
18+
)(.#)?(.rst)?
1019
exclude: >-
11-
^CHANGES/(\.TEMPLATE\.rst|\.gitignore|\d+\.(bugfix|feature|removal|doc|misc)(\.\d+)?(\.rst)?|README\.rst)$
20+
(?x)
21+
^
22+
CHANGES/(
23+
\.gitignore
24+
|(\d+|[0-9a-f]{8}|[0-9a-f]{7}|[0-9a-f]{40})\.(
25+
bugfix
26+
|feature
27+
|deprecation
28+
|breaking
29+
|doc
30+
|packaging
31+
|contrib
32+
|misc
33+
)(\.\d+)?(\.rst)?
34+
|README\.rst
35+
|\.TEMPLATE\.rst
36+
)
37+
$
1238
files: ^CHANGES/
1339
- id: changelogs-user-role
1440
name: Changelog files should use a non-broken :user:`name` role

‎CHANGES/.TEMPLATE.rst

+49-3
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,56 @@
1111
{{ underline * definitions[category]['name']|length }}
1212

1313
{% if definitions[category]['showcontent'] %}
14-
{% for text, values in sections[section][category].items() %}
14+
{% for text, change_note_refs in sections[section][category].items() %}
1515
- {{ text + '\n' }}
16-
{{ values|join(',\n ') + '\n' }}
17-
{% endfor %}
1816

17+
{#
18+
NOTE: Replacing 'e' with 'f' is a hack that prevents Jinja's `int`
19+
NOTE: filter internal implementation from treating the input as an
20+
NOTE: infinite float when it looks like a scientific notation (with a
21+
NOTE: single 'e' char in between digits), raising an `OverflowError`,
22+
NOTE: subsequently. 'f' is still a hex letter so it won't affect the
23+
NOTE: check for whether it's a (short or long) commit hash or not.
24+
Ref: https://github.com/pallets/jinja/issues/1921
25+
-#}
26+
{%-
27+
set pr_issue_numbers = change_note_refs
28+
| map('lower')
29+
| map('replace', 'e', 'f')
30+
| map('int', default=None)
31+
| select('integer')
32+
| map('string')
33+
| list
34+
-%}
35+
{%- set arbitrary_refs = [] -%}
36+
{%- set commit_refs = [] -%}
37+
{%- with -%}
38+
{%- set commit_ref_candidates = change_note_refs | reject('in', pr_issue_numbers) -%}
39+
{%- for cf in commit_ref_candidates -%}
40+
{%- if cf | length in (7, 8, 40) and cf | int(default=None, base=16) is not none -%}
41+
{%- set _ = commit_refs.append(cf) -%}
42+
{%- else -%}
43+
{%- set _ = arbitrary_refs.append(cf) -%}
44+
{%- endif -%}
45+
{%- endfor -%}
46+
{%- endwith -%}
47+
48+
{% if pr_issue_numbers -%}
49+
*Related issues and pull requests on GitHub:*
50+
:issue:`{{ pr_issue_numbers | join('`, :issue:`') }}`.
51+
{% endif %}
52+
53+
{% if commit_refs -%}
54+
*Related commits on GitHub:*
55+
:commit:`{{ commit_refs | join('`, :commit:`') }}`.
56+
{% endif %}
57+
58+
{% if arbitrary_refs -%}
59+
*Unlinked references:*
60+
{{ arbitrary_refs | join(', ') }}`.
61+
{% endif %}
62+
63+
{% endfor %}
1964
{% else %}
2065
- {{ sections[section][category]['']|join(', ') }}
2166

@@ -34,3 +79,4 @@ No significant changes.
3479
{% endif %}
3580
{% endfor %}
3681
----
82+
{{ '\n' * 2 }}

‎CHANGES/.gitignore

+27
Original file line numberDiff line numberDiff line change
@@ -1 +1,28 @@
1+
*
2+
!.TEMPLATE.rst
13
!.gitignore
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+
!*.misc
24+
!*.misc.rst
25+
!*.misc.*.rst
26+
!*.packaging
27+
!*.packaging.rst
28+
!*.packaging.*.rst

‎CHANGES/8066.contrib.rst

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The changelog categorization was made clearer. The
2+
contributors can now mark their fragment files more
3+
accurately -- by :user:`webknjaz`.
4+
5+
The new category tags are:
6+
7+
* ``bugfix``
8+
9+
* ``feature``
10+
11+
* ``deprecation``
12+
13+
* ``breaking`` (previously, ``removal``)
14+
15+
* ``doc``
16+
17+
* ``packaging``
18+
19+
* ``contrib``
20+
21+
* ``misc``

‎CHANGES/8066.packaging.rst

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

‎CHANGES/README.rst

+19-6
Original file line numberDiff line numberDiff line change
@@ -43,19 +43,32 @@ with your own!).
4343
Finally, name your file following the convention that Towncrier
4444
understands: it should start with the number of an issue or a
4545
PR followed by a dot, then add a patch type, like ``feature``,
46-
``doc``, ``misc`` etc., and add ``.rst`` as a suffix. If you
46+
``doc``, ``contrib`` etc., and add ``.rst`` as a suffix. If you
4747
need to add more than one fragment, you may add an optional
4848
sequence number (delimited with another period) between the type
4949
and the suffix.
5050

5151
In general the name will follow ``<pr_number>.<category>.rst`` pattern,
5252
where the categories are:
5353

54-
- ``feature``: Any new feature
55-
- ``bugfix``: A bug fix
56-
- ``doc``: A change to the documentation
57-
- ``misc``: Changes internal to the repo like CI, test and build changes
58-
- ``removal``: For deprecations and removals of an existing feature or behavior
54+
- ``bugfix``: A bug fix for something we deemed an improper undesired
55+
behavior that got corrected in the release to match pre-agreed
56+
expectations.
57+
- ``feature``: A new behavior, public APIs. That sort of stuff.
58+
- ``deprecation``: A declaration of future API removals and breaking
59+
changes in behavior.
60+
- ``breaking``: When something public gets removed in a breaking way.
61+
Could be deprecated in an earlier release.
62+
- ``doc``: Notable updates to the documentation structure or build
63+
process.
64+
- ``packaging``: Notes for downstreams about unobvious side effects
65+
and tooling. Changes in the test invocation considerations and
66+
runtime assumptions.
67+
- ``contrib``: Stuff that affects the contributor experience. e.g.
68+
Running tests, building the docs, setting up the development
69+
environment.
70+
- ``misc``: Changes that are hard to assign to any of the above
71+
categories.
5972

6073
A pull request may have more than one of these components, for example
6174
a code change may introduce a new feature that deprecates an old

‎docs/spelling_wordlist.txt

+7
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Arsenic
1717
async
1818
asyncio
1919
asyncpg
20+
attrs
2021
auth
2122
autocalculated
2223
autodetection
@@ -34,6 +35,7 @@ backports
3435
BaseEventLoop
3536
basename
3637
BasicAuth
38+
behaviour
3739
BodyPartReader
3840
boolean
3941
botocore
@@ -89,6 +91,7 @@ Cythonize
8991
cythonized
9092
de
9193
deduplicate
94+
defs
9295
Dependabot
9396
deprecations
9497
DER
@@ -104,6 +107,7 @@ DNSResolver
104107
docstring
105108
docstrings
106109
DoS
110+
downstreams
107111
Dup
108112
elasticsearch
109113
encodings
@@ -313,6 +317,8 @@ Testsuite
313317
Tf
314318
timestamps
315319
TLS
320+
tmp
321+
tmpdir
316322
toolbar
317323
toplevel
318324
towncrier
@@ -329,6 +335,7 @@ Unittest
329335
unix
330336
unsets
331337
unstripped
338+
untyped
332339
uppercased
333340
upstr
334341
url

‎pyproject.toml

+67-6
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,73 @@ requires = [
55
build-backend = "setuptools.build_meta"
66

77
[tool.towncrier]
8-
package = "aiohttp"
9-
filename = "CHANGES.rst"
10-
directory = "CHANGES/"
11-
title_format = "{version} ({project_date})"
12-
template = "CHANGES/.TEMPLATE.rst"
13-
issue_format = "`#{issue} <https://github.com/aio-libs/aiohttp/issues/{issue}>`_"
8+
package = "aiohttp"
9+
filename = "CHANGES.rst"
10+
directory = "CHANGES/"
11+
title_format = "{version} ({project_date})"
12+
template = "CHANGES/.TEMPLATE.rst"
13+
issue_format = "{issue}"
14+
15+
# NOTE: The types are declared because:
16+
# NOTE: - there is no mechanism to override just the value of
17+
# NOTE: `tool.towncrier.type.misc.showcontent`;
18+
# NOTE: - and, we want to declare extra non-default types for
19+
# NOTE: clarity and flexibility.
20+
21+
[[tool.towncrier.section]]
22+
path = ""
23+
24+
[[tool.towncrier.type]]
25+
# Something we deemed an improper undesired behavior that got corrected
26+
# in the release to match pre-agreed expectations.
27+
directory = "bugfix"
28+
name = "Bug fixes"
29+
showcontent = true
30+
31+
[[tool.towncrier.type]]
32+
# New behaviors, public APIs. That sort of stuff.
33+
directory = "feature"
34+
name = "Features"
35+
showcontent = true
36+
37+
[[tool.towncrier.type]]
38+
# Declarations of future API removals and breaking changes in behavior.
39+
directory = "deprecation"
40+
name = "Deprecations (removal in next major release)"
41+
showcontent = true
42+
43+
[[tool.towncrier.type]]
44+
# When something public gets removed in a breaking way. Could be
45+
# deprecated in an earlier release.
46+
directory = "breaking"
47+
name = "Removals and backward incompatible breaking changes"
48+
showcontent = true
49+
50+
[[tool.towncrier.type]]
51+
# Notable updates to the documentation structure or build process.
52+
directory = "doc"
53+
name = "Improved documentation"
54+
showcontent = true
55+
56+
[[tool.towncrier.type]]
57+
# Notes for downstreams about unobvious side effects and tooling. Changes
58+
# in the test invocation considerations and runtime assumptions.
59+
directory = "packaging"
60+
name = "Packaging updates and notes for downstreams"
61+
showcontent = true
62+
63+
[[tool.towncrier.type]]
64+
# Stuff that affects the contributor experience. e.g. Running tests,
65+
# building the docs, setting up the development environment.
66+
directory = "contrib"
67+
name = "Contributor-facing changes"
68+
showcontent = true
69+
70+
[[tool.towncrier.type]]
71+
# Changes that are hard to assign to any of the above categories.
72+
directory = "misc"
73+
name = "Miscellaneous internal changes"
74+
showcontent = true
1475

1576

1677
[tool.cibuildwheel]

0 commit comments

Comments
 (0)