writing-issues-and-prs

编写 Issue 和 PR

无论使用哪个平台，文字都至关重要。除非用户或上下文要求使用特定平台术语，否则应保持平台中立。

如需了解适用于不同场景（Bug 报告、功能请求、PR/MR、工作项、评审评论）的结构，请阅读 references/outlines.md。这些结构只是示例，并非固定模板：应以此为起点，根据实际情况调整写作内容，按需重排、删减、添加、合并或新建章节。只要仓库或跟踪工具提供了自己的模板，就优先使用。

写作原则

• 简洁明了：删去不必要的词，精简重复和含糊其辞的表达，优先使用朴实、直接的文字。让每个词都发挥作用。如果内容无法放在一个屏幕内，就太长了。
• 准确、结构清晰、富有见地，语气沉稳、自然、人性化。保持审慎和严谨，仔细核查推理、来源和假设。
• 清楚说明问题、请求或目的，解释其重要性，并提供具体证据。
• 对于英文内容，遵循以下风格指南，并将其中与语言无关的规则应用于任何语言的文本：The Elements of Style、The Sense of Style 和 Chicago Manual of Style。

格式规则

• 英文单词与中日韩字符之间留空格。
• 无序列表使用 - （连字符加空格）；不要使用 * 或 + 。
• 斜体使用 _italics_，粗体使用 **bold**。
• 如果列表项都是片段，则省略句末句号；如果其中有完整句子，则每个列表项都以句号结尾。
• 不要使用水平分隔线（<hr> 或 ---）。

标题

• Issue 和工作项标题使用“句首字母大写”格式（仅首词首字母大写）。
• Pull request 和 merge request 标题采用 Conventional Commits 格式，并遵循 git-commit 技能：<type>[optional scope]: <description>。

正文标题

• 不要强行在文本开头加标题。只有在有助于理清结构时才使用标题；可以先写一段简短的开场句或段落。
• 标题层级应依次递进（先 h2，再 h3 等），不要跳级。
• 不要使用 h1，也不要为标题编号（例如，使用 ## 关于我，而不是 ## 1. 关于我）。