Skip to content

Commit cba3469

Browse files
webknjazwebknjaz
committed
Merge branch 'docs/change-note-guidelines'
PR #8066
2 parents a379e63 + a2a4a92 commit cba3469

38 files changed

+289
-36
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 32 additions & 10 deletions
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 <Name> <Surname>.
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‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -436,8 +436,10 @@ jobs:
436436
version_file: aiohttp/__init__.py
437437
github_token: ${{ secrets.GITHUB_TOKEN }}
438438
dist_dir: dist
439-
fix_issue_regex: "`#(\\d+) <https://github.com/aio-libs/aiohttp/issues/\\1>`_"
440-
fix_issue_repl: "(#\\1)"
439+
fix_issue_regex: >-
440+
:issue:`(\d+)`
441+
fix_issue_repl: >-
442+
#\1
441443
442444
- name: >-
443445
Publish 🐍📦 to PyPI

‎.pre-commit-config.yaml‎

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

Lines changed: 49 additions & 3 deletions
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‎

Lines changed: 27 additions & 0 deletions
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/2835.removal renamed to CHANGES/2835.breaking.rst

File renamed without changes.

CHANGES/2977.removal renamed to CHANGES/2977.breaking.rst

File renamed without changes.

CHANGES/3463.removal renamed to CHANGES/3463.breaking.rst

File renamed without changes.

CHANGES/3538.removal renamed to CHANGES/3538.breaking.rst

File renamed without changes.

CHANGES/3539.removal renamed to CHANGES/3539.breaking.rst

File renamed without changes.

0 commit comments

Comments
 (0)