ydbms

Imported from theflysong/ydbms (AGENTS.md). Install upstream with npx skills add theflysong/ydbms. Copyright stays with the author.

AGENTS.md

本文件只放通用且持久的规则:它们与具体实现无关,也不会随功能演进失效.

**项目事实一律不写在这里.**它们有自己的位置,见下面两节.

一,项目事实从文档注释来

**动手之前,先读你要改的那个文件的文件头(//!).**不要从本文件,也不要凭记忆 或直觉去推断项目事实.

• 每个源文件都以 //! 开头,写它是什么,为什么这样设计,有哪些已知偏差与坑;
• crate 总览在 src/lib.rs 的文件头,模块总览在各自的 mod.rs 文件头;
• 不变量,算子语义,与参考实现的差异,踩过的坑,都在注释里,且随代码一起维护.

从哪儿出发(要找事实时先看这几个文件头):crate 总览在 src/lib.rs,各模块总览在 src/{db,ir,pers,cmd,usr}/mod.rs;用户 / 库 / 服务目录在 src/usr/,ysql 那条 命令行在 src/cmd/cli.rs.

**事实与注释不一致时,以代码为准,并把注释改对.**注释是事实通道,写错了比没有 更糟--它会被当成真的.

二,子模块的 AGENTS.md

子目录下可能有自己的 AGENTS.md,写该子模块的职能与特殊规则.

在针对某个子模块动手之前,必须主动去找并读完它:

1. 从你要改的文件所在目录起,向上逐级找 AGENTS.md,一直找到 crate 根;
2. 找到的全部读一遍,再动手;
3. 越靠近被改文件的越优先;冲突时以它为准;
4. 一层都没找到,就只用本文件.

不要假设你知道某个子模块是干什么的--去读.

三,通用规则

• 改完必须构建并测试:cargo test --offline.
• 零 warning:error 和 warning 都要清零.不要用 #[allow(...)] 把 warning 盖住.
• 测试以集成测试为主,数量够用即可,不追求覆盖率.
• 简单是美德:写出 200 行而本可以 50 行,就重写成 50 行.
• 不要为不可能发生的情况写错误处理.
• 测试失败时,先判断是代码错了还是测试的期望错了--两者都可能.不要默认 去改测试.
• 改了行为,就同步改文档注释和测试;三者不一致视为没做完.

四,注释

• 语言跟着文件走:看该文件现有的 //! 与 // 用什么语言,就用什么语言. 同一 crate 内不要混.
• 注释用 Markdown 语法(即使不渲染):"object 被借走了",而不是"object 被借走了".
• 注释写为什么和坑,不要复述代码.
• 标点一律半角,见下面的 "六,文案与标点".
• 公开项一律要有文档注释.

五,Rust

• 工具链,edition,依赖以 Cargo.toml 为准,不要擅自升级或替换.
• 加依赖前先问:现有的能不能做到?能不加就不加.
• 命名遵循 Rust 惯例(RFC 430).
• 优先不用 unsafe.确实需要时,每个 unsafe 块之前必须有 // SAFETY: 说明它 为什么成立--即使显而易见.
• 不要为了通过编译而随手 clone 或加生命周期;先把所有权说清楚.

六,文案与标点

文案一律走 tr!,不许硬编码

• 给用户看的文本不在代码里:源文案在 locales/zh-CN.yml(它是源语言), 译文在 locales/en.yml;调用点一律 tr!("模块.文件.序号", 名字 = 表达式). 机制,默认语言与换语言的入口见 i18n 的文件头.
• 键是 模块.文件.序号(序号 = 该文件里第几条文案,从 001 起).加一条就往后接 一个号,别手工排号:tests/i18n.rs 会核对"代码里用的键 ↔ 文案表里的键"是否 一一对应--两边缺哪条它都会点名.
• 占位符写法两边不同:文案表里写 %{名字},调用点写 名字 = 表达式;要格式说明符 就写 名字 = 表达式 : {:>4}.名字必须两边一致(同样是 tests/i18n.rs 在核).
• 注释不翻:注释是给读代码的人看的,中文注释就留在代码里,别搬进文案表.
• 例外:机器可读的协议行.psql 的命令标签(INSERT 0 N / UPDATE N / BEGIN / COMMIT / ROLLBACK)是协议而不是给用户看的文案,所以照 psql 原样打, 不走 tr!,也不进文案表--详见 src/cmd/AGENTS.md 的"命令标签".
• 加一种语言:在 locales/ 下加一份 <locale>.yml(键照抄),把标签加进 i18n::KNOWN_LOCALES 与 i18n::resolve,再跑 cargo test --test i18n.
• 改了文案要同时改两份 YAML,别只改一份.

标点尽可能用半角

中文注释,文案,文档里尽可能用半角标点;下面这些全角标点都有半角对应体, 一律换成右边那种(表里写的是码位,免得这张表自己就带着反例):

• 为什么:同一个仓库里混着两种宽度,读起来像两种排版;而且全角逗号,冒号在等宽 字体里占两格,表格与对齐全乱.
• 别背这张表:tests/i18n.rs 的 punctuation_is_halfwidth 会扫源码的注释与 字符串,文案表,以及我们自己的 *.md(课程给的 ydbms-test/ 不动),扫到就红, 并指名道姓告诉你哪个文件哪一行.
• 引用与强调:注释里要强调一个词就用半角 ",反引号留给代码标识符.
• 小心 markdown 链接:行内的 [代码] 后面紧跟左圆括号时,半角化之后就成了 一个 markdown 链接(cargo doc 会报"链接解析不到").中间补一个空格就对了.
• 中文本身当然照写;换的只是标点.

七,Git

• 提交信息用 Conventional Commits:

  <type>: <小写,祈使句的简短摘要>

  type 取 feat / fix / perf / refactor / docs / test / build / chore. 一次提交只做一件事,结尾不加句号.

  主体部分应以若干个主要点组成, 每个主要点附带若干个从要点(可以没有从要点). 每个主要点的从要点数量可以不同, 但必须能对该主要点起到补充说明的作用,非必要不要添加从要点. 格式类似于

  - 主要点 1
   - 次要点 1
   - 次要点 2
  - 主要点2
  ...
  

• 不要替用户提交,除非明确要求.

• 提交前先构建,测试,清 warning.