Atom 开源项目贡献指南：从 Bug 报告、代码风格到 Pull Request 规范

本文基于 Atom 仓库的官方贡献文档 docs/contributing.md 整理扩展，覆盖从定位问题所属仓库、提交规范的 Bug 报告与功能建议，到 Git 提交信息、JavaScript / CoffeeScript / 测试 / 文档四类代码风格规范，以及 issue 与 Pull Request 的标签体系。读完本文后，你可以独立判断某项改动应该提交到哪里，并按照 Atom 维护者能直接接受的标准撰写代码、测试与文档。

贡献前须知：行为准则与提问渠道

Atom 项目及其所有参与者都受 行为准则 约束。该准则采用 Contributor Covenant 1.4 版本，核心要求是使用包容性语言、尊重不同观点、以社区利益为重；不可接受的行为包括人身攻击、骚扰、未经许可以发布他人隐私等。不可接受行为可报告至 Atom 官方邮箱，维护者有义务对举报人保密。

文档特别强调：不要为提问开 issue。提问应走官方社区渠道（Atom 官方论坛 / FAQ），因为 issue 队列是留给可复现的缺陷和功能需求的，用 issue 提问只会拖慢两边的响应速度。

Atom 的模块化架构：先判断改动属于哪个仓库

Atom 由 200 多个仓库组成。文档建议的第一课是：在报 Bug 或提 PR 之前，先确定目标功能由哪个仓库实现。Atom 刻意采用高度模块化的设计——几乎所有编辑器之外的 UI 元素都来自独立包，连标签页和状态栏也不例外。这些"内置包"和社区包的唯一区别，是被打包进了 Atom 的默认发行版。

核心仓库与内置包

从源码结构看，这一说法可以直接在本仓库的 package.json 中得到印证：

• dependencies 中，一部分内置包以 file:packages/... 形式指向本仓库内的目录（如 about、git-diff、one-dark-ui），即这些包随 Atom 主仓库共同开发；
• 另一部分以 git+https://github.com/atom/...#commit 形式固定到某个提交（如 fuzzy-finder、tabs、status-bar、find-and-replace），即这些包在独立仓库中维护；
• packageDependencies 字段则列出发布时随发行版捆绑的包及其版本，其中 file:./packages/... 的条目正是内置包清单。

文档列出的主要仓库及职责：

仓库	职责
atom/atom	核心：光标、选区、滚动等基础编辑能力，缩进、软换行、折叠、文本渲染、文件系统操作（保存）、安装与自动更新；Atom API 反馈和大型设计方案也应提交到这里
tree-view	左侧文件/目录列表
fuzzy-finder	快速打开文件
find-and-replace	全部查找替换功能
tabs	顶部已打开编辑器的标签页
status-bar	底部状态栏
markdown-preview	Markdown 渲染面板
settings-view	设置界面面板
autocomplete-plus	输入时的自动补全（语言级补全另有 autocomplete-[language] 包，如 autocomplete-html）
git-diff	编辑器行槽中的 Git 变更指示
language-javascript 等	所有内置语言都是独立包，命名为 language-[name]；特定语言的语法高亮问题应报到对应语言包
one-dark-ui	编辑器之外部分的默认 UI 样式（-ui 后缀包只提供样式）
one-dark-syntax	默认语法高亮样式；"在多种语言都出现、换主题后消失"的高亮问题应报到语法主题包
apm	apm 命令行工具（Atom Package Manager）与包发布相关
atom.io	官网与包 API

由于 Atom 高度可扩展，也可能你遇到的功能或问题根本来自你自己安装的社区包——每个社区包同样有独立仓库。

包命名约定

文档总结了历史上形成的三类命名约定：

• 添加语法高亮规则的包命名为 language-[language-name]。语言包也可以附带常用 snippet 等，但不宜塞入过多无关功能；
• 主题包分为 UI 主题与语法主题两类：UI 主题命名 [theme-name]-ui，负责编辑器面板之外的一切样式；语法主题命名 [theme-name]-syntax，只负责编辑器面板内（主要是语法高亮）。配套使用的主题常共享同一前缀，例如 one-dark-ui 与 one-dark-syntax；
• 自动补全提供者命名为 autocomplete-[补全对象]，例如 autocomplete-css。

这些约定在本仓库的 packages/ 目录可以直接对照：one-dark-ui、one-light-syntax、solarized-dark-syntax、base16-tomorrow-dark-theme、language-rust-bundled 等目录与 package.json 中的 packageDependencies 条目一一对应。

设计决策文档

当项目就"如何维护、能支持什么、不能支持什么"做出重大决定时，官方会记录在 Atom 设计决策仓库（design-decisions）中。有疑问先查该仓库是否有既有记录；没有记录时再到官方讨论区提问，而不是直接开 issue 质问。

报告 Bug

提交前检查清单

1. 查调试指南：确认问题在最新版 Atom 中可复现、确认问题在 Safe Mode（安全模式）下是否出现、确认调整 Atom 或包的配置项能否消除问题——多数情况下你能自己定位原因；
2. 查 FAQ 和官方讨论区，确认不是常见已知问题；
3. 按上一节的方法确定问题应报到哪个仓库；
4. 粗略搜索 issue，若已有相同问题且仍 open，在旧 issue 下评论而不是开新 issue。若发现的是 Closed 的相同 issue，则开新 issue 并在正文中引用原 issue。

一份合格 Bug 报告应包含的内容

问题描述与复现

• 使用清晰、有信息量的标题；
• 给出尽可能详尽的复现步骤，并且不只说"做了什么"，还要说"怎么做的"——例如把光标移到行尾时，说明用的是鼠标、快捷键还是 Atom 命令，具体是哪个；
• 提供可复现的具体示例：文件链接、GitHub 项目，或可直接粘贴的代码块；
• 描述实际观察到的行为，并指出其中具体哪里有问题；
• 说明你期望的行为及原因；
• 附上截图或动图 GIF。使用键盘操作时，请在 Keybinding Resolver 可见的状态下录制，以证明按键映射过程；
• 报告崩溃时，附上操作系统崩溃报告及堆栈（macOS 下位于 Console.app 的"诊断和使用情况信息 > 用户诊断报告"），以代码块、附件或 gist 形式提供；
• 性能或内存问题，附上 DevTools 的 CPU profile 抓取；
• 若 Chrome 开发者工具面板在未触发情况下自动弹出，通常是某个主题或你自己的 styles.less 有语法错误——尝试 Safe Mode、更换主题或注释 styles.less 内容验证；
• 问题不是由某次特定操作触发时，描述问题发生前你在做什么，并按下方指引补充信息。

环境与配置信息

• Atom 版本：终端执行 atom -v，或启动后从 Command Palette 运行 Application: About；
• 操作系统名称与版本；是否在虚拟机中运行（VM 软件、宿/客机系统版本）；
• 已安装包列表：apm list --installed；
• 是否使用本地配置文件 config.cson、keymap.cson、snippets.cson、styles.less、init.coffee 定制 Atom，若是请贴出内容。本仓库根目录的 dot-atom/ 目录即 Atom 默认配置目录，其中的 init.coffee、keymap.cson、snippets.cson、styles.less 就是这套机制的模板；
• 是否多显示器环境，单显示器下能否复现；键盘布局（US 还是其他）；
• 与文件相关的问题，还需说明：是否所有文件/项目都出现，还是仅本地/远程（如网络盘）、特定类型、超大文件或超长行、特定编码的文件。

时序信息：问题是否近期才出现（如更新后）？能否在旧版本复现？最后一个不出现的版本是哪个？能否稳定复现？不能稳定复现时说明频率与触发条件。

建议功能增强

提交前检查清单

1. 查调试指南与配置项——你要的增强可能已经存在；
2. 查社区包仓库——可能已有包实现了该增强；
3. 确定应建议到哪个仓库；
4. 粗略搜索，已有相同建议时评论旧 issue 即可。

一份合格功能建议应包含的内容

• 清晰有信息量的标题；
• 分步骤描述建议的增强，越细越好，并附可粘贴的示例代码块；
• 描述当前行为，说明期望行为及原因；
• 附截图或 GIF 指明涉及 Atom 的哪部分界面；
• 解释为何该增强对多数用户有价值，且不适合实现为社区包；
• 列举其他已具备该功能的文本编辑器或应用作为参考；
• 注明 Atom 版本（atom -v）与操作系统版本。

第一次代码贡献与本地开发

不确定从哪入手时，从带有 beginner（只需几行代码加一两个测试）和 help-wanted（比 beginner 稍复杂）标签的 issue 开始。这两个 issue 列表按评论数降序排列，评论数可以近似看作改动影响面的代理指标。

Atom Core 与所有包都支持本地开发。官方手册中对应两个章节：Hacking on Atom Core 与 Contributing to Official Atom Packages。本仓库内的 docs/contributing-to-packages.md 就是一个指向官方手册对应章节的跳转说明。从本仓库结构可以推断本地开发的日常工作流：

• 测试：package.json 中 test 脚本指向 script/test，它通过 yargs 暴露 --core-main（核心主进程测试）、--core-renderer（核心渲染进程测试）、--core-benchmark（核心基准测试）、--package（内置包规格）等开关，并要求先完成构建（否则报错提示先运行 script/build）；
• Lint：script/lint 会并行执行 CoffeeScript、JavaScript、LESS 三路检查（script/lib/lint-coffee-script-paths.js、script/lib/lint-java-script-paths.js、script/lib/lint-less-paths.js），任一报错即以非零码退出——这正是 PR 状态检查会失败的原因之一；
• 打包/发布流水线辅助脚本集中在 script/lib/ 下，如 package-application.js、create-debian-package.js、create-rpm-package.js 等，了解构建链路时可以从这里入手。

Pull Request 规范

文档为 PR 流程设定了四个目标：维护 Atom 的代码质量、修复对用户重要、社区参与、让维护者可持续地审查贡献。提交流程要求：

1. 遵循 PULL_REQUEST_TEMPLATE.md 中的全部说明；
2. 遵循后文全部风格规范；
3. 提交 PR 后确认所有状态检查（status checks）通过。若某项检查失败且你判断与本次改动无关，在 PR 中留言说明理由，由维护者重跑；若确认检查本身误报，官方会开 issue 跟踪该问题。

查看 PULL_REQUEST_TEMPLATE.md 的实际内容，它要求按贡献类型选择对应模板并填全所有部分，共四套：

• 修 Bug：Bug Fix 模板；
• 性能优化：Performance 模板；
• 更新文档：Docs 模板；
• 行为/功能变更：Behavior 模板。

满足上述前置条件只是进入评审的门槛，评审人仍可能要求补充设计工作、测试或其他改动后才最终接受。

代码风格规范

Git 提交信息

• 使用现在时（"Add feature" 而非 "Added feature"）；
• 使用祈使语气（"Move cursor to..." 而非 "Moves cursor to..."）；
• 首行不超过 72 个字符；
• 首行之后可以大量引用相关 issue 与 PR；
• 仅改文档时，在提交标题中加入 [ci skip]；
• 建议以相应 emoji 开头：:art: 改进代码格式/结构；:racehorse: 提升性能；:non-potable_water: 修复内存泄漏；:memo: 写文档；:penguin: 修复 Linux 问题；:apple: 修复 macOS 问题；:checkered_flag: 修复 Windows 问题；:bug: 修 Bug；:fire: 删除代码或文件；:green_heart: 修 CI 构建；:white_check_mark: 增加测试；:lock: 安全相关；:arrow_up: / :arrow_down: 升级/降级依赖；:shirt: 移除 linter 警告。

JavaScript 风格

所有 JavaScript 代码使用 Prettier 检查格式化。额外约定：

• 优先用对象展开运算符 {...anotherObj} 而不是 Object.assign()；
• 尽量把 export 内联到表达式上：

// 推荐：
export default class ClassName {

}

// 不推荐：
class ClassName {

}
export default ClassName

• require 顺序：Node 内置模块（如 path）→ Atom/Electron 内置模块（如 atom、remote）→ 相对路径本地模块；
• 类成员顺序：静态方法与属性在前，实例方法与属性在后；
• 避免平台相关代码，跨平台兼容需查阅官方手册对应章节。

CoffeeScript 风格

• 参数默认值等号两侧不留空格：clear = (count=1) -> 而非 clear = (count = 1) ->；
• 运算符两侧留空格：count + 1 而非 count+1；
• 逗号后留空格（换行分隔时除外）；
• 括号能提升可读性时就加；
• 偏好英文关键字而非符号：a is b 而非 a == b；
• hash 字面量大括号内不留空格：{a: 1, b: 2} 而非 { a: 1, b: 2 }；
• 方法之间保留一空行；
• 缩写词首字母大写，但单词首词小写：getURI 而非 getUri；
• 用 slice() 拷贝数组；
• 函数以 for/while 结尾且不希望返回收集数组时，显式 return；
• 使用 this 而非孤立的 @（return this 而非 return @）；
• require 顺序与类成员顺序规则同 JavaScript，仅"类成员"判断以 @ 开头的方法为准。

这些约定不是空文：本仓库根目录的 coffeelint.json 将多条规则设为 error 级强制检查，包括 no_stand_alone_at（禁用孤立 @，对应"用 this 替代 @"规则）、prefer_english_operator（对应 is 优先规则）、braces_spacing（spaces: 0，对应大括号内不留空格）、colon_assignment_spacing（左 0 右 1）、arrow_spacing、spacing_after_comma 等，与文档中的 CoffeeScript 风格条目一一吻合。

Specs（测试）风格

• 在包的 ./spec 目录中提交措辞讲究、结构良好的 Jasmine 规格；
• describe 当作名词或情境来写；
• it 当作一句关于状态或"操作如何改变状态"的陈述来写：

describe 'a dog', ->
  it 'barks', ->
    # spec here
  describe 'when the dog is happy', ->
    it 'wags its tail', ->
      # spec here

文档风格

• 使用 AtomDoc 与 Markdown；
• 在 Markdown 中用 {} 记法引用符号：类用 {ClassName}，实例方法用 {ClassName::methodName}，类方法用 {ClassName.methodName}。

一个符合该规范的真实示例来自 src/package-manager.js 中 disablePackage 的 AtomDoc 注释：

# Public: Disable the package with the given name.
#
# * `name`    The {String} name of the package to disable.
# * `options` (optional) The {Object} with disable options (default: {}):
#   * `trackTime`     A {Boolean}, `true` to track the amount of time taken.
#   * `ignoreErrors`  A {Boolean}, `true` to catch and ignore errors thrown.
# * `callback` The {Function} to call after the package has been disabled.
#
# Returns `undefined`.
disablePackage: (name, options, callback) ->

对照源码实现可以看到：disablePackage 通过 loadPackage(name) 取到包实例，在包未被 core.disabledPackages 禁用且已加载时调用其 disable()；其头部的 AtomDoc 注释同时承担了 API 文档生成（AtomDoc）与人类可读说明两个用途。

Issue 与 Pull Request 标签体系

标签帮助维护者跨仓库追踪和管理 issue / PR。大多数标签在全部 Atom 仓库通用，少数仅 atom/atom 使用。标签可按目的检索（例如"查找所有 open 且被标记为 bug 但尚需稳定复现的 Atom 相关 issue"），并非要求每个 issue 从每组都取一个标签，同一组内也可叠加多个。对新标签有建议、或发现某仓库缺标签，应分别在对应仓库开 issue 提出。

Issue 类型与状态

标签	说明
enhancement	功能请求
bug	已确认的 bug，或极大概率是 bug 的报告
question	偏提问而非报障或功能请求（如"如何做 X"）
feedback	一般性反馈，偏重于报障与功能请求之外
help-wanted	核心团队希望社区帮忙解决的 issue
beginner	复杂度较低的 issue，适合想参与 Atom 贡献的新手作为首个 issue
more-information-needed	还需收集更多信息（如复现步骤）
needs-reproduction	疑似 bug，但尚未稳定复现
blocked	被其他 issue 阻塞
duplicate	与其他 issue 重复
wontfix	核心团队决定暂不修复（如本就是预期行为）
invalid	无效 issue（如用户操作错误）
package-idea	更适合做成新包而非扩展 Atom 或核心包的功能请求
wrong-repo	报错了仓库（如 Settings View 包的 bug 报到了 Atom 核心仓库）

主题分类

标签	说明
windows / linux / mac	与 Atom 在对应平台上的运行相关
documentation	与任何类型的文档相关（API 文档、官方手册等）
performance	与性能相关
security	与安全相关
ui	与视觉设计相关
api	与 Atom 公开 API 相关
uncaught-exception	未捕获异常，通常由 Notifications 包自动创建
crash	Atom 整体崩溃报告
auto-indent	与自动缩进相关
encoding	与字符编码相关
network	网络问题或远程文件（如网络盘）相关
git	与 Git 功能相关（如 gitignore 处理、文件状态显示错误）

atom/atom 仓库专属主题标签

标签	说明
editor-rendering	与语言无关的文本渲染方面（滚动、软换行、字体渲染等）
build-error	从源码构建 Atom 时的问题
error-from-pathwatcher	pathwatcher 库抛出的错误
error-from-save	保存文件时抛出的错误
error-from-open	打开文件时抛出的错误
installer	各操作系统安装包相关
auto-updater	各操作系统自动更新器相关
deprecation-help	帮助包作者移除已废弃 API 用法的 issue
electron	需要修改 Electron 才能修复或实现的问题

Pull Request 标签

标签	说明
work-in-progress	仍在开发中，后续还会有更多改动
needs-review	需要代码评审与维护者/核心团队批准
under-review	正在由维护者或核心团队评审
requires-changes	需要根据评审意见修改后再次评审
needs-testing	需要手工测试

小结

docs/contributing.md 的主线是：先判断改动归属（核心仓库 / 内置包 / 社区包），再按类型走对应流程（提问走论坛、缺陷走规范 Bug 报告、功能走规范建议、代码走 PR + 状态检查），全程遵守四套风格规范与标签体系。结合本仓库的 package.json、coffeelint.json、PULL_REQUEST_TEMPLATE.md、script/lint 与 script/test 等实际文件，可以确认文档中的每一条规范都有对应的检查机制在背后执行，这也是你的贡献能否顺利通过评审的客观依据。