Cosmopolitan 贡献指南：版权转让、`__notice` 署名机制与代码风格规范全解析

• 标准库
• 操作系统
• 语言运行时
• 系统编程

导读

Cosmopolitan 是一个"build-once run-anywhere"的 C 库，其贡献流程与大多数开源项目不同：项目不接受匿名贡献，且首次提交 Pull Request 前需要向作者 Justine Tunney 完成一次版权转让声明。本篇指南以仓库根目录的 CONTRIBUTING.md 为骨架，逐条解读身份披露、版权转让、测试与第三方代码的例外政策、以及 clang-format 代码风格要求，并结合仓库源码（如__notice()署名机制的实际用法、tool/emacs/cosmo-format.el的实现）进行纵深剖析。读完本文，你将完整掌握向 Cosmopolitan 合规提交补丁的全流程，以及如何让自己的名字被嵌入到每一个链接了你的代码的可执行文件中。

一、贡献前必读：身份披露（Identity Disclosure）

Cosmopolitan 的贡献政策第一条就非常明确：项目不接受匿名贡献。维护者 Justine Tunney 不会合并陌生人的 Pull Request。想要修改 Cosmo 代码库并让改动被上游接纳，她必须知道你是谁。

具体操作上：

• 你被鼓励在 git commit message 中公开你的全名和邮箱地址；
• 但这不是强制要求——如果你希望对外保持匿名，项目同样尊重你的意愿。

这一政策的核心在于版权与责任的可追溯性：Cosmopolitan 的贡献流程建立在"贡献者与维护者之间建立可验证的身份关联"之上，这与后文将要详述的版权转让制度是一体两面。

二、版权转让（Copyright Assignment）：一次性邮件声明

2.1 流程与适用对象

首次发送 Pull Request 时，你需要向 Justine Tunney（jtunney@gmail.com）发送一封邮件，声明你有意将所贡献代码的版权转让给她。关键要点：

• 只需要做一次，后续贡献无需重复声明；
• 仅适用于你选择贡献的代码，不涉及你未提交的任何内容；
• 邮件必须从与你的身份相关联的邮箱发出；
• 邮件中应附上你的 Pull Request 链接，以便维护者核对。

2.2 官方推荐邮件模板

CONTRIBUTING.md 给出了可直接套用的英文邮件模板，核心结构如下：

From: YOUR NAME (yname@gmail.com)To: Justine Tunney (jtunney@gmail.com)Subject: Cosmopolitan Copyright Assignment for YOUR NAME

Hi Justine,

I made my first contribution to Cosmopolitan in pull request XXXX. Could you please take a look? I intend to assign you the copyright to the changes I contribute to Cosmopolitan.

Thanks!

（原文中的 PR 链接请替换为你实际提交的 Pull Request 编号。）

2.3 在职贡献者的注意事项

要转让版权，前提是版权本来就属于你。如果你受雇于某家公司：

• 需要事先获得雇主的授权；
• 文档特别指出，即便是 Google 这样的大公司，这一授权流程通常也很快——一般一天之内即可获批。

2.4 无法转让版权的情况

如果你所在的国家/地区法律不承认个人转让版权的能力，可以选择放弃版权（disclaim），使用 Unlicense 或 CC-0 公有领域声明中的语言来表达同等意图。这为不同法域的贡献者提供了替代路径。

三、版权政策的例外：测试代码与特殊功能

3.1 测试代码（Tests）：鼓励署名

测试代码是例外中的第一类，政策明确鼓励贡献者主张测试代码的所有权：

• 如果你在test/目录下新增文件，应在文件顶部的 ISC 许可证头中写上你的名字；
• 如果你向已有的单元测试文件追加用例，鼓励在既有版权头中追加一行你的名字。

这一约定在仓库中可以得到印证：test/目录按模块划分（如test/libc/、test/posix/、test/ctl/），每个子目录都有对应的 BUILD.mk 构建文件，测试源码以*_test.c后缀命名并通过$(wildcard test/libc/runtime/*.c)等规则自动纳入构建体系。测试代码的署名政策，正是为了让贡献者对测试用例的归属一目了然。

3.2 特殊功能（Exceptional Features）：__notice()署名机制

这是 Cosmopolitan 最具特色的贡献政策。假设你发现了一种更快、更好的方式来实现log10()，并想把它贡献给 Cosmopolitan——这类"从零重写的高价值算法"并不适合由维护者独占版权。此时你可以：

1. 从零编写你自己的log10.c；
2. 在文件顶部署名并采用 ISC 许可证；
3. 添加一个__notice()指令，使你的名字被嵌入每一个链接了log10()函数的可执行文件中。

这样一来，你的名字会随编译产物分发出去，帮助你获得知名度。文档同时提醒：每次这样做之前，都需要获得 Justine 的批准。

这一机制在仓库源码中有真实用例。例如 libc/log/err.c 中，BSD 风格的错误库代码在版权头之后、实际实现之前，通过如下方式声明其来源：

// clang-format off __notice(freebsd_err_notice, "\ FreeBSD Error Library (BSD-3 License)\n\ Copyright 1993 The Regents of the University of California");

从这段源码可以看出__notice()的实际形态：第一个参数是通知符号名，第二个参数是嵌入可执行文件的署名文本（可包含许可证名称、版权持有者等信息），且通常配合// clang-format off使用，避免自动格式化破坏多行字符串的排版。整段声明紧跟在完整的 BSD-3 许可证头部之后，与 CONTRIBUTING.md 描述的"在文件顶部用 ISC 许可证署名 +__notice()嵌入名字"流程完全对应。

四、第三方代码的贡献规范

如果你要签入（check-in）第三方代码，CONTRIBUTING.md 规定了严格的格式要求：

• 每个源文件（注意：头文件除外）的顶部都需要有记录其所有者的头部；
• 代码必须放入third_party/目录；
• 每个第三方项目都应有一个README.cosmo文件，记录其来源（provenance）以及你做的本地改动。

仓库中这一规范得到了大量落实。find结果显示third_party/下存在大量README.cosmo文件（如 awk、bzip2、chibicc、mbedtls、sqlite3 等），此外libc/tinymath/README.cosmo、dsp/mpeg/README.cosmo等非 third_party 目录也沿用了同样的约定。

以 third_party/awk/README.cosmo 为例，其结构清晰展示了溯源要求：

DESCRIPTION The One True Awk This is the version of awk described in The AWK Programming Language, by Al Aho, Brian Kernighan, and Peter Weinberger ... SOURCE https://github.com/onetrueawk/awk commit 2bab10b60b3f4d3bbefdcb60410655f317d1a452 date Thu Mar 14 14:25:30 2024 +0200

而 libc/tinymath/README.cosmo 则展示了许可证说明的写法：

LICENSE All code is covered by notice licenses (e.g. BSD, MIT) which are documented on a file-by-file basis. ORIGIN git://git.musl-libc.org/musl commit f5f55d6589940fd2c2188d76686efe3a530e64e0 ...

从这些实例可以总结出README.cosmo的通用构成：DESCRIPTION（描述）、SOURCE/ORIGIN（精确到 commit 的上游来源）、LICENSE（许可证说明），必要时再加上你所做的本地改动记录。这为第三方代码的合规审计提供了完整可追溯的证据链。

五、代码风格指南（Style Guide）

5.1 clang-format 一键格式化

Cosmopolitan 推荐使用 clang-format 自动格式化代码，官方命令为：

clang-format -i -style=file tool/net/redbean.c

关键点在于-style=file：它指示 clang-format 读取项目根目录下的.clang-format配置文件（而非使用内置默认风格），保证所有贡献者的格式与项目既有代码一致。

5.2 Emacs 自动格式化：cosmo-format.el

如果你使用 Emacs，可以通过 tool/emacs/cosmo-format.el 在保存时自动格式化。深入阅读该文件可以发现它的工作机制相当完善：

安装方式（文件头部注释说明）：

;; Put the following in your .emacs.d/init.el file: (require 'cosmo-format) ;; Put this file in the root of your project: ;; printf '---\nBasedOnStyle: Google\n...\n' >.clang-format

触发条件：任何路径名匹配cosmo-format-path-regex的缓冲区，在保存时若满足以下两个条件即自动格式化：

1. 能找到 clang-format 程序（或自定义cosmo-format-bin）；
2. 目录树中存在.clang-format文件（或自定义cosmo-format-arg，此时建议按 buffer 局部定制）。

可配置项（defcustom）：

实现细节：

• 程序查找按版本降序探测clang-format-10至clang-format-7再回退到clang-format（见 cosmo-format.el）；
• 通过--assume-filename=传入相对于项目根目录的文件路径，配合-style=file保证按项目配置格式化；
• 使用临时文件 +call-process+replace-buffer-contents的方式在缓冲区原地替换格式化结果；
• 若文件首行以/* clang-format off */或// clang-format off开头，则跳过格式化——这与__notice()多行字符串的排版保护需求相呼应；
• 仅在 Emacs 26.3+ 上挂载before-save-hook，因为依赖replace-buffer-contents函数。

这套配置的意义在于：格式化的判定完全交给-style=file与项目内.clang-format文件，贡献者无需记忆任何风格规则，保存即合规。

六、贡献流程速查清单

将 CONTRIBUTING.md 的要点汇总为一份可执行清单：

1. 身份：在 commit message 中披露全名与邮箱（项目不接受匿名贡献）；
2. 首次版权声明：第一个 PR 提交后，从本人邮箱向 jtunney@gmail.com 发送版权转让邮件（含 PR 链接），之后永久豁免；
3. 在职确认：若受雇于人，先取得雇主授权；
4. 例外政策：
   • 新增测试文件：在 ISC 头中署名；
   • 追加测试用例：在既有版权头追加名字；
   • 从零实现特殊功能：ISC 署名 +__notice()指令（需逐次获批）；
5. 第三方代码：放入third_party/，源文件（非头文件）顶部记录所有者，并附README.cosmo记录来源与本地改动；
6. 代码风格：clang-format -i -style=file <文件>格式化；Emacs 用户启用 cosmo-format.el 自动格式化。

结语

Cosmopolitan 的贡献指南在通用开源协作规范之上，叠加了三层项目特有的制度设计：强制身份披露确保版权流转的可验证性；一次性版权转让 + 测试/特殊功能署名例外在保护维护者权益的同时，让贡献者对自己的代码保有署名与知名度；而__notice()嵌入机制与README.cosmo溯源规范则从技术与合规两个维度，保证了"build-once run-anywhere"的每一个可执行文件都能精确追溯到每一行代码的出处。对有意加入的开发者而言，遵守这份指南不仅是流程要求，也是理解 Cosmo 独特工程文化的最佳入口。

• 标准库
• 操作系统
• 语言运行时
• 系统编程