Back to Details

write-issue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing and maintaining GitHub issues

撰写和维护GitHub Issue

Standards for issues in tldraw/tldraw.
tldraw/tldraw仓库的Issue规范。

Title standards

标题规范

  • Sentence case - Capitalize only the first word and proper nouns
  • No type prefixes - Use GitHub issue types, not 
    Bug:
    , 
    Feature:
    , 
    [Bug]
    , etc.
  • Imperative mood for enhancements - "Add padding option" not "Adding padding option"
  • Descriptive for bugs - Describe the symptom: "Arrow bindings break with rotated shapes"
  • Specific - Readable without opening the issue body
  • 句子大小写 - 仅首字母和专有名词大写
  • 无类型前缀 - 使用GitHub Issue类型，而非
    Bug:
    , 
    Feature:
    , 
    [Bug]
    等
  • 增强功能采用祈使语气 - 例如使用“Add padding option”而非“Adding padding option”
  • Bug标题需描述症状 - 如“Arrow bindings break with rotated shapes”（旋转图形时箭头绑定失效）
  • 标题需具体 - 无需打开Issue正文即可理解内容

Good titles

规范标题示例

  • Arrow bindings break with rotated shapes
  • Add padding option to zoomToFit method
  • Pinch zoom resets selection on Safari
  • Arrow bindings break with rotated shapes
  • Add padding option to zoomToFit method
  • Pinch zoom resets selection on Safari

Bad titles

不规范标题示例

  • Bug: arrow bug
    (prefix, vague)
  • [Feature] Add new feature
    (prefix, vague)
  • Not working
    (vague)
  • Bug: arrow bug
    （带前缀、表述模糊）
  • [Feature] Add new feature
    （带前缀、表述模糊）
  • Not working
    （表述模糊）

Title cleanup transformations

标题清理规则

  1. Remove prefixes: 
    Bug: X
    → 
    X
  2. Fix capitalization: 
    Add Padding Option
    → 
    Add padding option
  3. Use imperative: 
    Adding feature X
    → 
    Add feature X
  4. Be specific: 
    Problem
    → 
    [Describe the actual problem]
  5. Translate non-English titles to English
  1. 移除前缀：
    Bug: X
    → 
    X
  2. 修正大小写：
    Add Padding Option
    → 
    Add padding option
  3. 改为祈使语气：
    Adding feature X
    → 
    Add feature X
  4. 细化表述：
    Problem
    → 
    [描述实际问题]
  5. 将非英文标题翻译为英文

Issue types

Issue类型

Set via the GitHub GraphQL API after creating the issue (the 
--type
flag is not reliably supported):
TypeUse for
Bug
Something isn't working as expected
Feature
New capability or improvement
Example
Request for a new SDK example
Task
Internal task or chore
创建Issue后通过GitHub GraphQL API设置（
--type
参数支持不可靠）：
类型适用场景
Bug
功能未按预期工作
Feature
新增功能或功能改进
Example
请求新增SDK示例
Task
内部任务或日常事务

Labels

标签

Use sparingly (1-2 per issue) for metadata, not categorization.
标签应少用（每个Issue建议1-2个），用于元数据标记而非分类。

Common labels

常用标签

LabelUse for
good first issue
Well-scoped issues for newcomers
More Info Needed
Requires additional information
sdk
Affects the tldraw SDK
dotcom
Related to tldraw.com
a11y
Accessibility
performance
Performance improvement
api
API change
标签适用场景
good first issue
适合新手的范围明确的Issue
More Info Needed
需要补充更多信息
sdk
影响tldraw SDK
dotcom
与tldraw.com相关
a11y
无障碍访问相关
performance
性能优化相关
api
API变更相关

Automation labels (do not apply manually)

自动化标签（请勿手动添加）

keep
, 
stale
, 
update-snapshots
, 
publish-packages
, 
major
, 
minor
, 
skip-release
, deploy triggers
keep
, 
stale
, 
update-snapshots
, 
publish-packages
, 
major
, 
minor
, 
skip-release
, deploy triggers

Issue body standards

Issue正文规范

Bug reports

Bug报告

  1. Clear description of what's wrong
  2. Steps to reproduce
  3. Expected vs actual behavior
  4. Environment details (browser, OS, version) when relevant
  5. Screenshots/recordings when applicable
  1. 清晰描述问题现象
  2. 提供复现步骤
  3. 对比预期行为与实际行为
  4. 提供相关环境细节（浏览器、操作系统、版本）（如适用）
  5. 附上截图/录屏（如适用）

Feature requests

功能请求

  1. Problem statement - What problem does this solve?
  2. Proposed solution - How should it work?
  3. Alternatives considered
  4. Use cases
  1. 问题说明 - 该功能解决什么问题？
  2. 提议的解决方案 - 功能应如何实现？
  3. 考虑过的替代方案
  4. 使用场景

Example requests

示例请求

  1. What API/pattern to demonstrate
  2. Why it's useful
  3. Suggested approach
  4. Which example category it belongs to
  1. 要演示的API/模式
  2. 说明其实用价值
  3. 建议的实现思路
  4. 所属的示例类别

Triage workflow

分类流程

New issues

新Issue处理

  1. Verify sufficient information to act on
  2. Set appropriate issue type
  3. Clean up title if needed
  4. Add 
    More Info Needed
    label and comment if details missing
  5. Add 
    good first issue
    if appropriate
  1. 验证是否具备足够的可操作信息
  2. 设置合适的Issue类型
  3. 如有需要，优化标题
  4. 若信息缺失，添加
    More Info Needed
    标签并留言提醒
  5. 如适合新手处理，添加
    good first issue
    标签

Stale issues

陈旧Issue处理

  1. Review if still relevant
  2. Close if no longer applicable
  3. Add 
    keep
    label if should remain open
  4. Request updates if waiting on information
  1. 检查Issue是否仍具相关性
  2. 若不再适用则关闭Issue
  3. 若需保留则添加
    keep
    标签
  4. 若在等待补充信息，请求用户更新

Important

重要提示

  • Never include "Generated with Claude Code" unless the PR directly relates to Claude Code
  • Never use title case for descriptions - use sentence case
  • 除非PR直接与Claude Code相关，否则请勿包含“Generated with Claude Code”字样
  • 描述内容请勿使用标题大小写，统一使用句子大小写