Writing Issues and PRs
Whatever the platform, the writing carries the weight. Stay platform-neutral unless the user or surrounding context calls for platform-specific terms.
For starting structures by scenario (bug report, feature request, PR/MR, work item, review comment), read references/outlines.md. Those outlines are examples, not fixed templates: treat them as a starting point and shape the writing to the actual situation — reorder, drop, add, merge, or invent sections as the case demands. Prefer a repo's or tracker's own template whenever one exists.
Writing principles
- Be concise: omit needless words, cut redundancy and hedging, and prefer plain, direct prose. Make every word count. If it does not fit on one screen, it is too long.
- Be accurate, well-structured, and insightful, in a calm, natural, and human tone. Be skeptical and precise — double-check reasoning, sources, and assumptions.
- State the issue, request, or purpose clearly. Explain why it matters. Include concrete evidence.
- For English prose, follow these style guides, and apply their language-agnostic rules to prose in any language: The Elements of Style, The Sense of Style, and Chicago Manual of Style.
Formatting rules
- Insert spaces between English words and CJK characters.
- Use
- (hyphen plus space) for unordered list items; never use * or + .
- Use
_italics_ for italics and **bold** for bold.
- For list items, omit the trailing period when all items are fragments; if any item is a complete sentence, end every item with a period.
- Never use horizontal dividers (
<hr> or ---).
Titles
- Issue and work item titles use "Sentence case" (capitalize the first word only).
- Pull request and merge request titles use Conventional Commits format, following the
git-commit skill: <type>[optional scope]: <description>.
Body headings
- Do not force the text to begin with a heading. Use headings only when they add structural clarity; a short opening sentence or paragraph can come first.
- Use heading levels sequentially (
h2, then h3, etc.); never skip levels.
- Never use
h1, and never number headings (e.g., ## About me, not ## 1. About me).
1---2name: writing-issues-and-prs3description: Writes, edits, reviews, or improves concise titles, bodies, and comments for issues, pull requests, and merge requests on GitHub and GitLab, and for work items (tickets, stories, tasks, epics) on Jira, Linear, and similar issue and project trackers.4license: MIT5---67# Writing Issues and PRs89Whatever the platform, the writing carries the weight. Stay platform-neutral unless the user or surrounding context calls for platform-specific terms.1011For starting structures by scenario (bug report, feature request, PR/MR, work item, review comment), read [`references/outlines.md`](references/outlines.md). Those outlines are examples, not fixed templates: treat them as a starting point and shape the writing to the actual situation — reorder, drop, add, merge, or invent sections as the case demands. Prefer a repo's or tracker's own template whenever one exists.1213## Writing principles1415- Be concise: omit needless words, cut redundancy and hedging, and prefer plain, direct prose. Make every word count. If it does not fit on one screen, it is too long.16- Be accurate, well-structured, and insightful, in a calm, natural, and human tone. Be skeptical and precise — double-check reasoning, sources, and assumptions.17- State the issue, request, or purpose clearly. Explain why it matters. Include concrete evidence.18- For English prose, follow these style guides, and apply their language-agnostic rules to prose in any language: _The Elements of Style_, _The Sense of Style_, and _Chicago Manual of Style_.1920## Formatting rules2122- Insert spaces between English words and CJK characters.23- Use `- ` (hyphen plus space) for unordered list items; never use `* ` or `+ `.24- Use `_italics_` for italics and `**bold**` for bold.25- For list items, omit the trailing period when all items are fragments; if any item is a complete sentence, end every item with a period.26- Never use horizontal dividers (`<hr>` or `---`).2728### Titles2930- Issue and work item titles use "Sentence case" (capitalize the first word only).31- Pull request and merge request titles use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format, following the `git-commit` skill: `<type>[optional scope]: <description>`.3233### Body headings3435- Do not force the text to begin with a heading. Use headings only when they add structural clarity; a short opening sentence or paragraph can come first.36- Use heading levels sequentially (`h2`, then `h3`, etc.); never skip levels.37- Never use `h1`, and never number headings (e.g., `## About me`, not `## 1. About me`).
zlliang