1
- .. _Adding change notes with your PRs :
1
+ .. _Making a pull request :
2
+
3
+ Making a pull request
4
+ =====================
5
+
6
+ When making a pull request, please include a short summary of the changes
7
+ and a reference to any issue tickets that the PR is intended to solve.
8
+ All PRs with code changes should include tests. All changes should
9
+ include a changelog entry.
2
10
3
11
Adding change notes with your PRs
4
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12
+ ---------------------------------
5
13
6
14
It is very important to maintain a log for news of how
7
15
updating to the new version of the software will affect
8
16
end-users. This is why we enforce collection of the change
9
17
fragment files in pull requests as per `Towncrier philosophy `_.
10
18
11
19
The idea is that when somebody makes a change, they must record
12
- the bits that would affect end-users only including information
20
+ the bits that would affect end-users, only including information
13
21
that would be useful to them. Then, when the maintainers publish
14
22
a new release, they'll automatically use these records to compose
15
23
a change log for the respective version. It is important to
@@ -19,7 +27,7 @@ to the end-users most of the time. And so such details should be
19
27
recorded in the Git history rather than a changelog.
20
28
21
29
Alright! So how to add a news fragment?
22
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
30
+ ---------------------------------------
23
31
24
32
``aiohttp `` uses `towncrier <https://pypi.org/project/towncrier/ >`_
25
33
for changelog management.
@@ -34,11 +42,14 @@ for the users to understand what it means.
34
42
combined with others, it will be a part of the "news digest"
35
43
telling the readers **what changed ** in a specific version of
36
44
the library *since the previous version *. You should also use
37
- reStructuredText syntax for highlighting code (inline or block),
45
+ * reStructuredText * syntax for highlighting code (inline or block),
38
46
linking parts of the docs or external sites.
39
- If you wish to sign your change, feel free to add ``-- by
40
- :user:`github-username` `` at the end (replace ``github-username ``
41
- with your own!).
47
+ However, you do not need to reference the issue or PR numbers here
48
+ as *towncrier * will automatically add a reference to all of the
49
+ affected issues when rendering the news file.
50
+ If you wish to sign your change, feel free to add
51
+ ``-- by :user:`github-username` `` at the end (replace
52
+ ``github-username `` with your own!).
42
53
43
54
Finally, name your file following the convention that Towncrier
44
55
understands: it should start with the number of an issue or a
@@ -77,7 +88,7 @@ necessary to make a separate documentation fragment for documentation
77
88
changes accompanying the relevant code changes.
78
89
79
90
Examples for adding changelog entries to your Pull Requests
80
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
91
+ -----------------------------------------------------------
81
92
82
93
File :file: `CHANGES/6045.doc.1.rst `:
83
94
0 commit comments