Writing PR/MR bodies

The job of a PR/MR description is to compress what the reviewer needs to know that is not visible in the diff. Apply this test to every sentence.

To embed screenshots or video, read MEDIA.md. Check repository visibility with gh repo view --json isPrivate before choosing a URL; raw.githubusercontent.com images do not render from private repositories.

One block, one line

GitHub renders a single newline inside a paragraph as <br> in issue, pull-request, and discussion fields (documented; release notes behave the same in practice), so a hard-wrapped paragraph displays broken mid-sentence. Write each paragraph or list item as one line, however long, with a blank line between blocks — this renders correctly on every forge, including GitLab, whose fields follow standard Markdown paragraph rules. Markdown files in the repo (README, docs, CHANGELOG.md) render paragraphs normally; the rule applies the moment their content is pasted into a comment-style field — a changelog entry pasted into release notes is the common trap. Commit messages stay wrapped at 72 columns.

The necessity test

Before writing a sentence, ask: can the reviewer get this from a 30-second scan of the diff? If yes, cut it.

Cut, because the diff already says this: