AxVisor 组件质量要求

[aarkegz]

说明

基于以下原因，我们需要将 AxVisor 的可独立使用的核心组件发布到 crates.io：

1. 方便开发维护：使用版本号而非 Git 仓库地址 + 分支引用依赖项，可以避免仓库的更新造成开发人员突然无法正常编译的情况，从而提高依赖项的稳定性和可复现性。

2. 利于项目向外推广：crates.io 是 Rust 生态最主要的代码发布平台，发布后能更方便地让社区用户发现和使用 AxVisor 的组件，也更容易吸引外部贡献者参与项目。

3. 是提升代码质量的好时机：公开发布需要达到较高的工程质量标准，这促使我们对接口、文档、测试、架构等方面进行系统性审查和改进，避免内部使用时可能被忽视的问题。

4. 增强组件复用性与独立性：正式发布核心组件有益于增加并保持 AxVisor 模块间的低耦合设计，有利于 AxVisor 的长期演进。

要求

为了满足公开发布的质量条件，每一个 crate 都需要达到以下标准：

完整的注释

1. crate 本身、公开模块、所有公开的类型和函数都必须具备完整的文档注释，清楚说明其用途、使用方式和注意事项。

2. 为了保证文档的完整性，CI 中应包含 cargo doc 命令，并设置环境变量：RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links -D missing-docs" 以确保文档链接无误且文档缺失即构建失败。

完善的测试

1. 除了确实无法测试的低层硬件接口函数外，其他所有函数和类型都应具备合理的测试覆盖。包括文档注释中的示例测试（doctest）以及常规单元测试。

2. 对抽象程度较高、复用度较强的模块，应具有更全面的测试覆盖率，确保行为稳定可靠。

清晰的结构

1. crate 内部应有合理的模块划分，避免过深或过浅的模块层级。

2. 应清晰划分公共 API 与内部实现，避免无意中暴露内部接口。

直观的命名

1. 类型、函数、模块名称应准确表达其用途，符合 Rust 的命名规范（如模块使用 snake_case，类型使用 CamelCase 等），避免歧义、模糊和不通用的缩写。

2. 公共接口的命名应以使用者角度考虑，做到易用、可理解、易检索。

完整的 CI

crate 发布前应该确保仓库有完整的 CI，并包括以下内容：

1. 在所有需要支持的平台上构建，构建尽量无 warning；

2. 在 x86_64-unknown-linux-gnu 平台上测试；

3. 构建文档；

4. clippy 无错误，尽量无 warning；

完整的信息

Cargo.toml 中描述、协议、作者等信息应该完善。

更新维护列表

当任意 Crate 有更新时，及时更新 Crate 列表 https://github.com/arceos-hypervisor/axvisor-crates