pr-description

PR Descriptions

Write HoloViz PR descriptions in the first person, as work you did.

Follow the repo's PR template rather than inventing sections. Every HoloViz repo inherits it from the org-wide holoviz/.github repo, so fetch the current, authoritative sections from the raw template and fill each one in:

https://raw.githubusercontent.com/holoviz/.github/refs/heads/main/.github/pull_request_template.md

Contents

• Writing each part well
• Voice and style

Writing each part well

• Title: conventional-commit style (fix:, feat:, docs:, chore:) summarizing the change in one line.
• Description: 2-3 sentences in your own words on what changed and why, with the motivation and a minimal reproducible example. Write the example per the minimal-example skill so a reviewer can paste and run it unchanged. Flag any breaking change, API change, new dependency, or migration step prominently so a reviewer cannot miss it.
• Before / After: include for any observable or visual change (behavior, UI, plotting, rendered docs) with screenshots, GIFs, or video, labelled old versus new. Skip it when there is nothing to compare, such as docs or refactors.
• AI disclosure: if AI was used, name the tool and model (for example Claude Code + Opus) and how it was used, and never delete the section. Non-disclosure can result in a ban.

Voice and style

Write dense, causal prose rather than a padded list. When a PR makes several distinct changes, a short bullet list with one bullet per change works well, but two or three sentences in a paragraph are equally fine when the changes are closely related and don't need to be scanned independently. Use - for bullets, not *. Either way keep it skimmable.

• Lead with the change, then the mechanism, e.g. "This PR adds X, where ...". State what changed before how it works.
• One bullet per independent change that needs context beyond the diff. Trivial file changes (a one-line README addition, a standard config file, a pixi task update) are visible in the diff and do not need a bullet. Pack the cause and effect into each bullet rather than splitting across several, e.g. "Fixed the Viewer example, which created widgets before super().__init__(); values synced but notifications didn't, so callbacks never fired."
• Don't hard-wrap inside a bullet or paragraph: keep each bullet on a single line. A PR description is a GitHub comment field, where every single newline renders as a line break (unlike a committed .md file), so wrapping shows up as mid-sentence breaks.
• Chain cause and effect within a sentence ("captured once, meaning ...", "watches it, triggering ... so ...") instead of many short, disconnected ones.
• Explain the motivation once; don't justify every step or restate the diff. State what each part does and trust the reader and the diff for the rest. Drop implementation details (how a script parses, what regex it uses) that the diff already shows; a bullet should say what something does for the reviewer, not how it works internally.
• Keep concrete anchors (key identifiers, field names, a minimal example) even while compressing, so it stays specific.
• Reserve backticks for concrete symbols (obs_id, None, function and parameter names); let conceptual names read as plain prose.
• After drafting, run the deslop skill scanner on the description to catch LLM prose patterns (AI vocabulary, selling adverbs, em-dash overuse, negative parallelism). Fix every hit that isn't a false positive.