@@ -103,7 +103,7 @@ information on using pull requests.
103103
104104[ GitHub Help ] : https://help.github.com/articles/about-pull-requests/
105105
106- ### Commit messages
106+ ### Commit messages and PR descriptions
107107
108108Commit messages (upon merging) and PR messages should follow the [ Conventional
109109Commits] ( https://www.conventionalcommits.org/ ) style:
@@ -139,9 +139,36 @@ Common `type`s:
139139* ` revert: ` means a prior change is being reverted in some way.
140140* ` test: ` means only tests are being added.
141141
142+ For the body, follow this guidance:
143+
144+ * Briefly tells * why* the change is being made. This usually means
145+ briefly describing how a bug manifests or what can't be accomplished
146+ without the feature.
147+ * Briefly gives an overview of * how* the code is changed. This is to
148+ orient readers for the diff they're about to read and understand; it's
149+ not a verbatim description of what changed.
150+ * List unrelated or notable dev-only changes at the end. e.g. formatting an
151+ old file, cleaning up testing, adding test support code, etc.
152+
142153For the full details of types, see
143154[ Conventional Commits] ( https://www.conventionalcommits.org/ ) .
144155
156+ #### PR description example
157+
158+ ```
159+ fix(pypi): handle files with .exe extensions
160+
161+ Currently, if a file with `.exe` is seen, an error
162+ occurs because validation assumes unix-only filenames.
163+ This prevents using whls with pre-built .exe files in
164+ their data payload.
165+
166+ To fix, detect the target OS and use an OS-appropriate
167+ validation function.
168+
169+ * Also adds test helpers for detecting the current OS
170+ ```
171+
145172### Documenting changes
146173
147174Changes are documented in two places: CHANGELOG.md and API docs.
0 commit comments