Back to Details

simple-issue-description

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Simple Issue Description

简洁Issue描述

Write an issue a maintainer can understand in under a minute. Focus on what someone experiences and what should happen instead.
撰写一份维护者能在一分钟内理解的Issue。聚焦于用户当前的体验以及预期的行为。

Workflow

工作流程

  1. Read the supplied notes, conversation, issue, PR description, or diff. In a PR, also check for spec, design doc, or README changes — they often state the intent better than the description does.
  2. Identify the concrete problem. State who or what is affected when the source makes that clear.
  3. Describe the desired behavior without prescribing an implementation.
  4. Keep only context that helps someone understand or reproduce the problem.
  5. If the source is a PR or diff, describe the problem the change tries to solve, not the files or code it changes.
  6. Draft the issue immediately unless the problem and desired behavior cannot be determined. In that case, ask one short clarifying question.
One issue per problem. If the source bundles unrelated problems, draft the issue for the most significant one, list the others in a line each, and tell the contributor to split them into separate issues and separate pull requests.
If the source adds a capability instead of fixing a misbehavior, do not stage the absence as a bug. Describe what a user cannot do today and the full user experience of the feature: who uses it, from where, and what they see.
Do not invent user impact, reproduction steps, or certainty that the source does not support. If the source only shows cleanup, refactoring, or a possible code smell, say that no concrete problem is clear instead of manufacturing an issue — this rule wins over step 6. Reply with two or three sentences: what the source shows, and what evidence would make it issue-worthy.
If the source fixes a security weakness that is not already public, do not draft a public issue describing it. Suggest reporting it privately to the maintainer instead.
  1. 阅读提供的笔记、对话、Issue、PR描述或代码差异。如果是PR，还需查看规格说明、设计文档或README的变更——这些内容通常比描述更能清晰体现意图。
  2. 明确具体问题。若来源中明确说明，需指出受影响的对象或范围。
  3. 描述预期行为，但不要指定实现方案。
  4. 仅保留有助于理解或复现问题的上下文信息。
  5. 如果来源是PR或代码差异，描述该变更试图解决的问题，而非变更的文件或代码内容。
  6. 立即起草Issue，除非无法确定问题和预期行为。若无法确定，提出一个简短的澄清问题。
一个Issue对应一个问题。如果来源包含多个不相关的问题，针对最严重的问题起草Issue，将其他问题逐条列出，并告知贡献者将它们拆分为单独的Issue和Pull Request。
如果来源是新增功能而非修复问题，不要将功能缺失描述为Bug。描述用户当前无法完成的操作，以及该功能完整的用户体验：谁会使用它、使用场景是什么、能看到什么内容。
不要编造用户影响、复现步骤，或来源未提及的确定性结论。如果来源仅涉及代码清理、重构或潜在代码异味，应说明未发现明确的具体问题，而非强行创建Issue——此规则优先于第6步。回复时用两三句话说明：来源展示了什么内容，以及需要哪些证据才能将其转化为有价值的Issue。
如果来源修复了尚未公开的安全漏洞，不要起草公开的Issue进行描述。建议改为私下向维护者报告。

Writing rules

撰写规则

  • Use plain language and short sentences.
  • Keep the issue under 200 words unless it is clear that more is necessary to describe the reproduction steps or a large feature.
  • Lead with behavior, not code, architecture, or the proposed fix. A one-sentence plain-language cause is fine when the symptom cannot be understood without it.
  • Keep technical details only when they are necessary to reproduce or understand the problem. Limits and defaults that make the symptom make sense (batch sizes, quotas, caps) count as necessary.
  • Preserve useful evidence such as error messages, screenshots, links, and documentation references.
  • Do not mention that AI wrote or reviewed the issue.
  • Avoid filler, praise, roadmap language, and exhaustive edge cases.
  • Use the contributor's level of certainty. Do not present a guess as a confirmed bug; write "can" or "appears to" when the source describes a risk rather than an observed failure.
  • 使用平实语言和短句。
  • Issue内容控制在200字以内，除非确实需要更多内容来描述复现步骤或大型功能。
  • 以行为描述开头，而非代码、架构或提议的修复方案。当症状无法脱离原因理解时，可以用一句话平实说明原因。
  • 仅保留复现或理解问题所需的技术细节。能解释症状的限制条件和默认值（如批量大小、配额、上限）属于必要信息。
  • 保留有用的证据，如错误信息、截图、链接和文档引用。
  • 不要提及AI撰写或审核了该Issue。
  • 避免冗余内容、赞美之词、路线图相关表述和详尽的边缘案例。
  • 遵循贡献者的确定性程度。不要将猜测表述为已确认的Bug；当来源描述的是风险而非已观测到的故障时，使用“可能”或“似乎”等表述。

Output format

输出格式

The first line is the issue title — when filing on GitHub, put it in the title field instead of repeating it in the body. For a missing capability, title the outcome ("Flag pages with no structured data") rather than a fake bug ("Audits never mention structured data").
Omit the Extra context section when there is nothing useful to add. Constraints and scope notes belong there, including what is not affected when a maintainer would reasonably worry that it is.
markdown
undefined
第一行是Issue标题——在GitHub上提交时，将其放在标题栏中，不要在正文中重复。对于功能缺失的情况，标题应体现预期结果（如"Flag pages with no structured data"），而非虚假的Bug描述（如"Audits never mention structured data"）。
当没有有用信息可添加时，省略额外上下文部分。限制条件和范围说明应放在该部分，包括维护者可能担心受影响但实际未受影响的内容。
markdown
undefined

<Short title describing the problem or desired outcome>

<描述问题或预期结果的简短标题>

TL;DR

TL;DR

<In one or two sentences, explain what happens now and what should happen instead.>
<用一两句话说明当前情况以及预期的改进方向。>

What is happening?

当前情况

<Describe the current behavior in plain language. Include a concrete example when available.>
<用平实语言描述当前行为。如有可用的具体示例，请包含在内。>

What should happen?

预期行为

<Describe the desired behavior without proposing how to build it.>
<描述预期行为，但不要提出实现方案。>

Extra context

额外上下文

<Optional reproduction steps, error text, screenshots, links, or constraints.>
undefined
<可选：复现步骤、错误文本、截图、链接或限制条件。>
undefined

Example

示例

markdown
undefined
markdown
undefined

The chat jumps away from messages I am reading

The chat jumps away from messages I am reading

TL;DR

TL;DR

When I scroll up to read an older message, a new response moves me back to the bottom of the chat. The chat should stay where I left it until I choose to return to the latest message.
When I scroll up to read an older message, a new response moves me back to the bottom of the chat. The chat should stay where I left it until I choose to return to the latest message.

What is happening?

What is happening?

New responses automatically scroll the chat to the bottom, even when I am reading earlier messages.
New responses automatically scroll the chat to the bottom, even when I am reading earlier messages.

What should happen?

What should happen?

Keep my current scroll position and show that a new message is available.
undefined
Keep my current scroll position and show that a new message is available.
undefined