[imiric]

Ha. Almost always when I see PRs with such summaries I can assume that both the summary and the code has been AI-generated.

PRs in general shouldn't require elaborate summaries. That's what commit messages are for. If the PR includes many commits where a summary might help, then that might be a sign that there should be multiple PRs.

[diogolsq]

1. about looking artificial.

Granted, it is not only summaries that go into the description—how to test, if there is any pre-deploy or post-deploy setup, any concerns, external documentation, etc.

Less is more. A summary serves to clarify, not to endlessly add useless information.

⸻

2. about the usefulness of summaries.

Summaries always provide better information—straight to the point—than commits (which are historical records). This applies to any type of information.

When you’re reporting a problem by going through historical facts, it can lead to multiple narratives, added complexity, and convoluted information.

Summaries that quickly deliver the key points clearly and focus only on what’s important offer a better way to communicate.

If the listener asks for details, they already have a clear idea of what to expect. A good summary is a good introduction to what you are going to see in the commits messages and in the code changes.

______________________

3.About multiple Prs.

Summary helps to clarify what is scope creep (be it a refactor or unrelated code to the ticket);

it make it easier for the reviewer demand a split in multiple PRs.

examples: A non-summary PR/MR might lead to the question—“WHY is this code here?"

"he touched a class here, was he fixing something that the test missed out ? or is just a refactor?"

_______________

As a reviewer you can get those information by yourself, although summary helps you to get it much quicker.

[imiric]

> A non-summary PR/MR might lead to the question—“WHY is this code here?"

This is precisely what a (good) commit message should answer.

Commits are historical records, sure, but they can include metadata about the change, which should primarily explain why the change was made, what tradeoffs were made and why, and any other pertinent information.

This is useful not just during the code review process, but for posterity whenever someone needs to understand the codebase, while bisecting, etc. If this information is only in the PR, it won't be easy to reference later.

FWIW I'm not against short summaries in PRs that are exceptionally tricky to understand. The PR description is also useful as a living document for keeping track of pending tasks. But in the majority of cases, commit messages should suffice. This is why GitHub, and I'm sure other forges as well, automatically fill out the PR title and description with the commit information, as long as there's only one commit, which is the ideal scenario. For larger PRs, if it doesn't make sense to create multiple, I usually just say "See the commits for details".

[bloomca]

Depends on the business logic, sometimes summaries (or a short demo explanation) help a lot to understand the made tradeoffs, so the reviewer can contribute more without spending too much time. It is especially helpful if the part is somewhat isolated.

But most of the time it is not very necessary.