# Contributing to Moon Collections

感谢参与 `moon-collections`。项目面向 MoonBit 0.10.x，欢迎提交数据结构、测试、文档和性能改进。

## 开发环境

1. 安装 MoonBit 工具链。CI 当前使用 `0.10.3+16975d007`，本地应优先使用同版本或更新的稳定版本。
2. 克隆仓库并运行 `moon update`。
3. Windows 原生目标安装 MSYS2 UCRT64 MinGW GCC。

## 提交前检查

在仓库根目录执行：

```bash
moon fmt
moon fmt --check
moon check --fmt --deny-warn
moon check --target all --deny-warn
moon build --target all
moon test --target all --deny-warn
moon info
git diff --exit-code
```

`moon info` 会生成或更新各包的 `pkg.generated.mbti`，公共 API 变化必须在提交说明中解释。请不要提交 `_build/`、`.moon/`、`.repos/`、`.env` 或任何账号凭据。

## 代码与测试约定

- 新功能先写边界测试，再实现最小行为；测试文件放在对应包的 `*_test.mbt`。
- 保持包边界清晰，公共类型和方法放在实际拥有它们的包中。
- 公共 API 配套文档示例，示例应能被复制到 MoonBit 包中运行。
- 写清楚时间复杂度、空间复杂度和顺序/稳定性保证；不要把未经测量的性能形容词写进文档。
- 修改公共接口时同步检查 `.mbti` diff；仅格式变化不应引起公共 API 变化。

## 提交与 Pull Request

提交信息使用简短的 Conventional Commits 风格，例如：

- `feat(indexmap): add ordered entry access`
- `fix(bitset): ignore negative indices`
- `test(lru-cache): cover zero-capacity behavior`
- `docs: document benchmark reproduction`

Pull Request 请说明行为变化、测试命令和是否改变公共 API。GitHub 与 Gitlink 是同步镜像，发布前请确认两端的 `main` 指向同一提交。