跳转至

贡献指南

感谢你考虑为 Shortener 项目做出贡献！

行为准则

请友善和尊重他人。我们致力于为每个人提供一个友好、安全和欢迎的环境。

如何贡献

报告 Bug

如果你发现了 bug，请在 GitHub Issues 创建一个问题，并包含：

  • 清晰的标题和描述
  • 重现步骤
  • 预期行为和实际行为
  • 你的环境信息（操作系统、Rust 版本等）
  • 相关的日志或错误信息

建议新功能

我们欢迎新功能建议！请在 GitHub Discussions 中讨论你的想法。

提交代码

  1. Fork 仓库

点击 GitHub 页面右上角的 "Fork" 按钮。

  1. 克隆你的 Fork
git clone https://github.com/你的用户名/shortener.git
cd shortener
  1. 创建分支
git checkout -b feature/你的功能名称

  1. 进行更改

  2. 遵循现有的代码风格

  3. 为新功能编写测试
  4. 更新相关文档

  5. 确保所有测试通过

  6. 提交更改

git add .
git commit -m "添加：你的功能描述"

提交信息格式： - 添加： - 新功能 - 修复： - Bug 修复 - 文档： - 文档更新 - 重构： - 代码重构 - 测试： - 测试相关

  1. 推送到你的 Fork
git push origin feature/你的功能名称
  1. 创建 Pull Request

在 GitHub 上打开一个 Pull Request，描述你的更改。

开发设置

前提条件

  • Rust 1.98 或更高版本（由 mise 自动安装，无需手动管理）
  • mise（工具链管理器，自动安装 Rust / Node / pnpm / prek）
  • Git

设置开发环境

项目使用 mise 管理开发工具链（Rust、Node、pnpm、prek）， 进入仓库目录即自动加载根目录 mise.toml：

# 安装 mise（一次性）
curl https://mise.run | sh

# 克隆仓库
git clone https://github.com/jetsung/shortener.git
cd shortener

# 自动安装 mise.toml 声明的工具链
mise install

# 构建项目
mise exec -- cargo build

# 运行测试
mise exec -- cargo test

# 运行服务器（环境变量由 mise 自动加载 .env）
mise exec -- cargo run -p shortener-server

已在 shell 中激活 mise（mise activate）或配置 direnv 集成时，可省略 mise exec -- 前缀。

服务端环境变量（SERVER__ADDRESS 等）由 mise 自动加载仓库根目录 .env， 详见 环境变量参考。

开发工具

安装推荐的开发工具：

# 代码格式化和检查
cargo install cargo-watch
cargo install cargo-audit

# 或使用 just
just install-tools

代码风格

  • 使用 cargo fmt 格式化代码
  • 使用 cargo clippy 检查代码
  • 遵循 Rust 命名约定
  • 为公共 API 编写文档注释

运行测试

# 运行所有测试
cargo test

# 运行特定包的测试
cargo test -p shortener-server

# 运行测试并显示输出
cargo test -- --nocapture

# 运行基准测试
cargo bench

代码检查

在提交前运行：

# 格式化代码
cargo fmt

# 检查代码
cargo clippy -- -D warnings

# 运行测试
cargo test

# 或使用 just
just check

文档

更新文档

如果你的更改影响用户可见的行为，请更新相关文档：

  • README.md - 项目概述
  • docs/ - 详细文档
  • 代码注释 - 内联文档

构建文档

# 构建 Rust 文档
cargo doc --open

# 构建 Zensical 文档
make docs-build

# 或使用 just
just docs-build

Pull Request 指南

好的 PR 应该：

  • 解决一个明确的问题或添加一个明确的功能
  • 包含测试
  • 更新相关文档
  • 通过所有 CI 检查
  • 有清晰的提交信息
  • 保持较小的更改范围

PR 流程

  1. 确保你的分支是最新的
  2. 所有测试通过
  3. 代码已格式化和检查
  4. 文档已更新
  5. 提交 PR 并等待审查
  6. 根据反馈进行修改
  7. PR 被合并

发布流程

发布由维护者处理：

  1. 更新版本号并创建 Git 标签：just release 0.2.0 （自动同步 Cargo.toml、openapi.yml、shortener-frontend/package.json 三处版本号，再提交并打标签）
  2. 只同步版本号、不提交打标签：just bump-version 0.2.0 （不带参数 just bump-version 或 make bump-version 会默认读取 Cargo.toml 的当前版本同步）
  3. 构建发布二进制文件：just release-build

版本同步机制：根 Cargo.toml 的 workspace.package.version 是唯一版本源， 子 crate（server/cli/common）通过 version.workspace = true 继承，依赖声明用 workspace = true / path 引用（不带 version），因此 bump-version 只需改根 Cargo.toml 一处，后端二进制版本与前端 package.json 版本即全链路自动同步。 4. 发布到 GitHub Releases

获取帮助

如果你需要帮助：

许可证

通过贡献，你同意你的贡献将在 Apache-2.0 许可证下授权。

致谢

感谢所有贡献者！你的贡献使这个项目变得更好。

作者: Jetsung Chan i@jetsung.com