跳到主要内容

开发准则

本页适用于 Ithiltir、Ithiltir-node、文档站和发布脚本的变更。

基本原则​

  • 保持现有用户可见行为兼容。
  • 优先使用项目已有的数据结构、配置方式、脚本入口和错误语义。
  • 新抽象必须减少实际重复或复杂度。
  • 内部重构不应改变公开 API、配置项、CLI、协议字段、数据库迁移结果或发布包布局。
  • 代码和文档不得把未实现能力写成事实。

公共契约​

以下内容属于公共契约：

  • Dash HTTP API 的路径、方法、请求字段、响应字段和错误码。
  • Ithiltir-node 上报协议、CLI 参数、安装脚本行为和本地模式行为。
  • config.toml、环境变量、主题包、磁盘结构、指标结构和文件系统布局。
  • 数据库迁移、保留策略、聚合结果、流量计费语义和时区语义。
  • Release asset 名称、压缩格式、内置文件路径和自动安装依赖。

修改公共契约时，必须同步更新对应文档。无法保持兼容时，应提供迁移路径或明确版本边界。

实现要求​

  • 先复用已有模块边界，再考虑新增模块。
  • 不为单个调用点引入通用框架。
  • 不把临时开发命令、调试字段或未稳定接口写入文档。
  • 错误码应稳定、可匹配，并在文档中说明触发条件。
  • 配置默认值必须和代码默认值一致。
  • UI 状态重构、前端 store 迁移、hook 调整等内部实现不进入用户文档，除非改变了用户可见行为。

测试要求​

不要求所有变更都新增单元测试。

涉及以下内容时，应补充测试或走真实路径验证：

  • 公共 API、CLI、配置解析和错误语义。
  • 数据库迁移、序列化、聚合、保留策略和计费周期。
  • 状态机、并发、重试、缓存失效和权限判断。
  • 安装、打包、升级、发布资产和跨平台脚本。
  • 历史 bug 区域或容易产生边界差异的路径。

只验证当前实现细节、编译器已保证的行为或纯内部重命名的测试不应新增。

文档要求​

  • 用户可见行为改变时，同步更新中文文档和英文文档。
  • API、错误码、配置项和数据结构应写在参考页或组件页。
  • 运维影响应写在运维页或配置页。
  • 发布、构建、工具链和贡献规则应写在 开发和发布 分组。
  • 文档只描述稳定入口、限制和结果，不记录临时开发过程。

发布要求​

  • 版本号必须符合 SemVer。
  • 发布包命名、内置节点版本和资产路径必须和发布说明一致。
  • 脚本依赖、Node.js 版本、GoReleaser 版本和系统依赖变化必须同步更新构建文档。
  • 发布说明应列出用户可见变化、迁移要求、兼容性影响和已知限制。