Serendipity
ce8063431e
- 为 core 公开 API 添加完整 doc comments（rustdoc 可用） - 新增 .editorconfig / CONTRIBUTING / CODE_OF_CONDUCT / SECURITY - 新增 Issue 模板（bug + feature）+ PR 模板 - 新增 3 个代码示例（examples/） - 更新 Cargo.toml 元数据（description/repository/keywords/categories/MSRV） - 更新 README + CHANGELOG
106 lines
2.2 KiB
Markdown
106 lines
2.2 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对 QRGen 的关注！这份指南帮助你了解如何参与项目。
|
||
|
||
## 项目架构
|
||
|
||
QRGen 是 Rust workspace，四层架构：
|
||
|
||
| crate | 用途 | 技术栈 |
|
||
|-------|------|--------|
|
||
| `qr-core` | 核心算法库 | Rust，纯算法无三方依赖 |
|
||
| `qrgen` | CLI 命令行 | clap + anyhow |
|
||
| `qrgen-gui` | 桌面应用 | Tauri 2.x + React 18 + TypeScript |
|
||
| `qrgen-web` | Web 服务 | axum 0.8 + tokio |
|
||
|
||
详细架构见 [CLAUDE.md](CLAUDE.md)。
|
||
|
||
## 开发环境
|
||
|
||
- **Rust** 1.95+ (`stable-x86_64-pc-windows-gnu` 或 `stable-x86_64-unknown-linux-gnu`)
|
||
- **Node.js** 22+（仅 GUI 前端需要）
|
||
- **pnpm**（GUI 前端包管理）
|
||
|
||
## 本地构建
|
||
|
||
```bash
|
||
# 克隆
|
||
git clone git@lhy-git.liuhangyv.top:Serendipity/QRGen.git
|
||
cd QRGen
|
||
|
||
# 安装 GUI 前端依赖
|
||
cd gui/src-frontend && pnpm install && cd ../..
|
||
|
||
# 编译检查
|
||
cargo check
|
||
|
||
# CLI
|
||
cargo build -p qrgen
|
||
|
||
# Web
|
||
cargo build -p qrgen-web
|
||
|
||
# GUI（需要前端依赖）
|
||
cd gui/src-frontend && pnpm build && cd ../..
|
||
cargo build -p qrgen-gui
|
||
```
|
||
|
||
## 提交规范
|
||
|
||
使用 Conventional Commits 格式：
|
||
|
||
```
|
||
<type>: <简短描述>
|
||
|
||
feat: 添加 Logo 图片支持
|
||
fix: 修复 PNG margin 全黑问题
|
||
refactor: 提取 fill_module 辅助函数
|
||
docs: 更新 README 安装说明
|
||
test: 添加格式信息 roundtrip 测试
|
||
```
|
||
|
||
类型：`feat` `fix` `refactor` `docs` `test` `chore` `perf` `ci`
|
||
|
||
## 代码风格
|
||
|
||
- **Rust**: `cargo fmt` + `cargo clippy -- -D warnings` 必须通过
|
||
- **TypeScript**: `pnpm tsc --noEmit` 必须通过（strict 模式）
|
||
- 注释用中文，标识符用英文
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 全量测试
|
||
cargo test # 所有 crate
|
||
|
||
# 仅核心库
|
||
cargo test -p qr-core
|
||
|
||
# 特定测试
|
||
cargo test -p qr-core -- mask # 掩码相关测试
|
||
|
||
# 覆盖率
|
||
cargo tarpaulin --out Html
|
||
```
|
||
|
||
测试覆盖率目标 ≥ 80%。
|
||
|
||
## 提交流程
|
||
|
||
1. Fork 仓库
|
||
2. 创建功能分支 (`git checkout -b feat/my-feature`)
|
||
3. 编码 + 测试（遵循 TDD）
|
||
4. `cargo fmt` + `cargo clippy -- -D warnings`
|
||
5. `cargo test` 全部通过
|
||
6. 提交并 push
|
||
7. 创建 Pull Request
|
||
|
||
## Issue 规范
|
||
|
||
- Bug 报告：附重现步骤 + 预期/实际行为
|
||
- 功能请求：描述使用场景和期望效果
|
||
|
||
## 感谢
|
||
|
||
所有贡献者将在 [README.md](README.md) 中致谢。
|