OpenDesign 新手贡献指南PR 与 Issue 的语音规则newcomer-tone【免费下载链接】open-design Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. ️ Local-first desktop app. ️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images video — real files, HTML/PDF/PPTX/MP4 export. Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode 20 CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-design对于第一次向 OpenDesignOD提交 PR 或 Issue 的新手贡献者正文语气往往比代码本身更影响维护者的第一印象。本文基于仓库内 .claude/skills/od-contribute/references/newcomer-tone.md 中的语音规则结合od-contribute技能的脚本与模板实现完整讲解 OD 社区对 PR/Issue 文案的硬性要求、软性建议、反模式、标题规范与先问后写的边界帮助你写出能被维护者顺利合入的贡献文本。为什么 OD 把语气当作硬规则OD 是一个小而有意为之small on purpose的开源项目正如 CONTRIBUTING.md 所言项目的大部分价值存放在文件里——Skill、Design System、prompt 片段——而非框架代码。维护者每天会阅读大量 PR因此在长期社区反馈文档中引用的[[feedback_outreach_minimal]]基础上沉淀出了一条核心判断PR body 是唯一能塑造维护者对这位贡献者第一印象的地方——让它温暖warm、简短brief、有用useful。newcomer-tone.md因此被定位为od-contribute技能在生成 PR/Issue 文案时必须遵守的语音规范。该技能在 SKILL.md 中明确将PR 标题、commit message、PR/Issue body 文件、分支名必须使用英文作为强制要求而正文的语气则由本文件约束。也就是说语言用英文语气按 newcomer-tone内容不过度承诺。硬规则不可违背的四条底线文档给出了四条硬规则Hard rules任何 PR/Issue 文案都必须遵守。1. PR body 结尾必须包含两样东西一行温暖的问候语例如 This is my first OD contribution.或类似的一行式致意OD Discord 邀请链接https://discord.gg/qhbcCH8Am4。关于 Discord 链接文档强调一个关键工程约束必须从OD_DISCORD_INVITE环境变量读取绝不硬编码。这一要求在 scripts/config.sh 中有对应实现: ${OD_DISCORD_INVITE:https://discord.gg/qhbcCH8Am4}即默认值是上述链接但允许通过环境变量覆盖。各 PR 模板在渲染时都通过{{DISCORD_INVITE}}占位符注入该值例如 PR-BODY-skill.md 的结尾If you want to chat (or youre another newcomer reading this and want help shipping your first PR), come hang out in the OD Discord:{{DISCORD_INVITE}}2. 绝不过度声称 PR 的实际内容一个拼写修复就是拼写修复——不要把它包装成提升文档质量也不要列出 5 个虚假的 checkbox。这条规则直接对应create-pr.sh中用非行话的 commit message的实现哲学以及各模板中Checklist 反映 validator 真正检查了什么的约定见下文软规则。3. 只用平实的语言禁止使用ergonomic、DX、stakeholder、stack rank这类创业公司博客腔词汇。要像一个友好的用户那样说话而不是像一篇 startup blog。注意 create-pr.sh 源码中commit message 直接使用$TITLE且不添加任何形容词前缀正是这一规则的工程体现。4. Emoji 数量严格受限除开头的之外只允许在标题或第一行出现一个可选的提交作品/翻译/文档/Bugemoji。OD 虽然热爱设计但维护者要读大量 PR过多的 emoji 只会增加噪音。软规则提升被合入概率的写作技巧硬规则之外文档给出四条软规则Soft rules它们不强制但强烈建议规则说明先说改了什么而不是为什么/怎么改维护者能通过 diff 看懂怎么改你只需陈述变更本身为什么最多 23 句若需要更多篇幅解释说明这个改动对 skill 来说太大了——请改为开 Issue 讨论可见变更配一张截图零张也可以截图不是必需项有则一张即可Checklist 要反映 validator 实际检查的内容不要照搬通用的仪式化清单这四条与模板中的 Checklist 一一对应。以 PR-BODY-skill.md 为例其清单只有三项且全部可被validate-skill-submission.sh验证SKILL.md的 frontmatter 包含name和descriptionSKILL.md中的每个相对路径都能解析没有路径逃逸出 skill 文件夹等待维护者 review而 PR-BODY-docs.md 的清单则是Markdown 仍能干净解析无损坏的 fence 或结构所有链接和图片路径仍能解析等待维护者 review可以看到这些 checkbox 都是 validatorvalidate-skill-submission.sh、validate-design-system.sh、validate-markdown.sh实际会执行检查的项而非凑数的仪式清单。反模式五件绝对不能做的事文档明确列出五个反模式全部对应社区的真实维护痛点不要写ask小节——不要写please review when you have timePR 本身就是请求不要邀请维护者电话/DM 你——Discord 才是沟通渠道这正解释了为什么每条 PR 都要带 Discord 邀请不要道歉——不要写Sorry if this isnt right如果不对维护者会告诉你不要加TL;DR——如果摘要还需要 TL;DR说明摘要本身太长了不要在语气上模仿 startup blog承接硬规则 3。这些反模式在模板中的落地方式很有意思PR-BODY-skill.md的结尾虽然写了 Hi! If anything looks off, tell me what to change and Ill happily push a fixup commit.但这不是道歉而是主动承诺跟进修复——把抱歉写得不好转化为告诉我怎么改语气从被动转为主动。标题规范commit 与 PR 的命名表文档提供了一张标题规范表适用于git commit和gh pr create --title。这张表被 SKILL.md 的 Step 8 直接引用--title PR title from references/newcomer-tone.md类型格式示例SkillAdd Skill: nameAdd Skill: invoice-templateDesign SystemAdd Design System: brandAdd Design System: notioni18nTranslate doc to LangTranslate QUICKSTART to Spanishi18n刷新Update Lang translation of docUpdate zh-CN translation of README文档拼写Fix typo in fileFix typo in README.md文档其他verb noun in whereClarify daemon setup in QUICKSTARTBugIssue 标题observed on surfacePreview iframe is blank on Safari 17几条实用的落地要点Bug 标题格式observed on surface与 templates/ISSUE-BODY-bug.md 的正文结构呼应——Issue 标题写现象 载体正文再展开步骤复现、预期行为、版本与平台i18n 标题的 Translate ... to ... 格式与 PR-BODY-i18n.md 的**{{DOC_NAME}}** → **{{LANG_DISPLAY_NAME}}**结构一致类型标签由 create-pr.sh 按贡献类型自动附加skill/design-system打good first issueenhancementi18n打i18ndocumentationdocs打documentation——标题表与标签体系共同构成 OD 的贡献分类学。何时应该先问再写文档最后给出先问后写When to ask before writing的边界如果用户想提交的成果在语气上不同寻常——例如一篇 manifesto 风格的博客、一个有争议的重构、或者用没有授权商标的真实公司名命名品牌——必须暂停并向用户确认。Better to skip the PR than ship something the maintainer will close politely.与其提交一个会被维护者礼貌关闭的 PR不如不发。这条边界在技能层面也有呼应od-repo-map.md 列出了技能的禁区——apps/daemon/src/、apps/web/src/、packages/、plugins/、tools/、e2e/都不在本技能管辖范围涉及真实代码评审或 Playwright 测试应引导用户走 TDD 管线技能而非提交一份注定被拒的 PR。在实践中如何落实从模板到gh pr createnewcomer-tone.md不是孤立文档而是整个od-contribute技能输出链路的一环。一次典型的新手贡献会这样落实语气规则Step 3a用户提交 Skill/Design Systemagent 询问署名名、一句话 pitch、可选截图路径渲染模板以 PR-BODY-skill.md 为例替换{{SKILL_NAME}}、{{SKILL_SLUG}}、{{PITCH}}、{{MOTIVATION}}、{{TRY_PROMPT}}、{{SCREENSHOT_BLOCK}}、{{DISCORD_INVITE}}七个占位符写入$WORKDIR/.od-contrib/PR-BODY.mdStep 7 预览确认向用户展示将要提交的分支、文件清单、diff 摘要与 PR body 前 40 行等待显式 Ship it 确认绝不未经确认就推送Step 8 提交create-pr.sh --workdir ... --type skill --title Add Skill: invoice-template --body-file ...脚本自动完成 stage、commitcommit message 即标题保持非行话、push 与gh pr create并在 stdout 单独一行输出 PR URL。整个流程中语气规则约束的是人写的部分pitch、motivation、标题、checklist 描述而模板与脚本保证结构部分Discord 邀请、类型标签、分支安全不遗漏。这也正是 OD 社区把newcomer-tone.md放在references/目录而非直接写死在脚本里的原因规则需要被理解、被翻译进各种语言、并在每个 PR 中由贡献者本人内化执行。【免费下载链接】open-design Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. ️ Local-first desktop app. ️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images video — real files, HTML/PDF/PPTX/MP4 export. Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode 20 CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考