Skip to content

Commit 913228c

Browse files
retpolanneRomuloOliveira
authored andcommitted
Add notes on good cover letters
Cover letters, or PR messages, are very important for "selling" your changes to the maintainers, and those are ofter overlooked. Add notes on good cover letters, inspired by kernel development git best practices. Signed-off-by: Anne Macedo <annie@retpolanne.com>
1 parent 2189fe6 commit 913228c

File tree

1 file changed

+14
-0
lines changed

1 file changed

+14
-0
lines changed

README.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,20 @@ Resolves: #123
247247
See also: #456, #789
248248
```
249249

250+
## Notes on PR messages and cover letters
251+
252+
Most developers open Pull Requests (PR) on a Git repo through a platform (Github, Gitlab),
253+
while kernel developers and people who send patches through email ([yes, that's a
254+
thing](https://git-scm.com/docs/git-send-email/2.45.0) refer to it as "cover letter".
255+
256+
A good cover letter, or PR message, will summarize, give background and context to a series of
257+
commits that are related. Good writing on this part will help to "sell" your commit series to
258+
the maintainers of a project, as they'll be able to understand why you are presenting such changes
259+
together.
260+
261+
If you're writing a smaller (single or a few commits) change, treat the first commit as a cover letter.
262+
Github, for example, uses this first commit as the default PR message.
263+
250264
## Rebase vs. Merge
251265

252266
This section is a **TL;DR** of Atlassian's excellent tutorial, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).

0 commit comments

Comments
 (0)