# 贡献 meta-unit-core

[English](CONTRIBUTING.md)

我们热烈欢迎你为 `meta-unit-core`（大道 OS 的基础微内核）做出贡献。你的努力将帮助塑造赛博生命计算的未来！

---

## 1. 贡献前须知

在开始之前，请花一点时间阅读以下指南：

* **行为准则：** 请阅读并遵守我们的 [行为准则](CODE_OF_CONDUCT.md)（即将推出）。我们致力于营造一个开放、包容的环境。
* **开发指南：** 按照我们的 [开发指南](GUIDE.md) 设置你的开发环境。这能确保你拥有所有必要的工具和一致的设置。
* **理解愿景：** 熟悉 [大道操作系统项目](https://nest.doylee.cn/dao-os/Dao-OS-Project) 的整体愿景，以及 `meta-unit-core` 在其中扮演的角色。

---

## 2. 如何贡献

我们遵循**基于主干开发 (Trunk-Based Development - TBD)** 的工作流，以确保快速迭代和持续集成。

### 报告 Bug

如果你发现了 Bug，请在我们的 [Gitea 工单追踪器](https://nest.doylee.cn/dao-os/meta-unit-core/issues) 上提交一个工单。

* **先搜索：** 检查现有工单，看 Bug 是否已被报告。
* **清晰描述：** 提供 Bug 的清晰简洁描述。
* **重现步骤：** 包含重现 Bug 的详细步骤。
* **预期行为与实际行为：** 描述你期望发生的情况和实际发生的情况。
* **环境：** 提供你的环境详细信息（操作系统、Rust 版本、Docker 版本等）。

### 提出增强或新功能建议

我们热爱新想法！如果你有建议：

* **提交工单：** 在 [工单追踪器](https://nest.doylee.cn/dao-os/meta-unit-core/issues) 上详细描述你的想法。
* **理由：** 解释为什么这个增强或功能对项目有价值。
* **潜在设计：** 如果你对如何实现有想法，请一并包含。

### 你的首次代码贡献

对于你的首次贡献，可以考虑在我们的 [工单追踪器](https://nest.doylee.cn/dao-os/meta-unit-core/issues) 上查找标记为 `good first issue` 或 `help wanted` 的工单。

### 代码贡献工作流 (TBD)

1.  **拉取最新主干代码：** 始终从 `main` 分支拉取最新的更改到你的本地机器。
    ```bash
    git pull origin main
    ```
2.  **创建短生命周期的特性分支：** 为了你的本地开发，创建一个新分支。这个分支应该专注于一个单一的、小的、原子性的更改，并尽快合并回 `main`。
    ```bash
    git checkout -b feature/my-new-awesome-thing
    # 或者用于 Bug 修复：
    git checkout -b bugfix/fix-that-issue
    ```
    *命名约定：* 优先使用 `feature/`、`bugfix/`、`docs/`、`refactor/` 前缀。
3.  **开发与测试：**
    * **测试驱动开发 (TDD)：** 我们鼓励在编写代码*之前*编写测试，以确保代码的正确性和可维护性。
    * 进行小而逻辑性的提交，并附上清晰的提交信息。
    * 确保所有现有测试通过（`cargo test`）。
    * 为你的更改添加新测试。
4.  **格式化和代码检查：** 在提交之前，请确保你的代码符合我们的风格指南。
    ```bash
    cargo fmt --all           # 应用格式更改
    cargo clippy --all-targets --all-features -- -D warnings # 运行 linter，将所有警告视为错误
    ```
5.  **推送你的分支：**
    ```bash
    git push origin your-branch-name
    ```
6.  **创建拉取请求 (PR)：**
    * 访问我们的 [Gitea 仓库](https://nest.doylee.cn/dao-os/meta-unit-core)，并从你的分支向 `main` 分支创建一个新的拉取请求。
    * **PR 标题：** 使用清晰、简洁的标题总结你的更改。
    * **PR 描述：** 提供你的更改的详细描述，为什么进行这些更改，任何相关的工单号，以及如何测试它们（如果适用）。
    * **CI 检查：** 确保所有持续集成 (CI) 检查通过。
7.  **快速审查与合并：** 你的 PR 将被快速审查。一旦通过批准且 CI 通过，它将被合并到 `main`。我们目标是小而频繁的合并。
8.  **大型功能使用特性开关：** 对于跨越多个 PR 或开发周期的大型或未完成的功能，直接提交到 `main`，但用 [特性开关 (feature flags)](https://docs.rs/feature-flags/latest/feature_flags/) 包裹新代码。这确保 `main` 分支始终保持稳定和可发布状态。

---

## 3. 代码风格和约定

* **Rust 格式化：** 我们使用 `rustfmt` 来强制执行代码风格。提交前务必运行 `cargo fmt`。
* **Clippy：** 我们使用 `clippy` 进行代码检查。所有 `clippy` 警告都必须解决（`cargo clippy --all-targets --all-features -- -D warnings`）。
* **提交信息：** 遵循清晰简洁的提交信息约定（例如，[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)）。
    * *示例：* `feat: 添加新的 IPC 机制` 或 `fix: 解决任务调度器中的竞争条件`
* **文档：** 所有公共函数、结构体、枚举和模块都应该有清晰的 Rustdoc 注释 (`///`)。强烈鼓励提供示例。

---

## 4. 社区与交流

* **工单追踪器：** [https://nest.doylee.cn/dao-os/meta-unit-core/issues](https://nest.doylee.cn/dao-os/meta-unit-core/issues) （用于 Bug、功能和讨论）
* **聊天/论坛：** （如果建立了 Discord、Matrix 或论坛，可以在此处添加链接）
* **拉取请求：** 用于提交代码更改。

感谢你对 `meta-unit-core` 贡献的兴趣！我们期待你的贡献。

---