贡献指南

感谢你对 Sea Lantern 项目的关注！这份文档将帮助你了解如何为项目做出贡献。

可接受 PR 范围

对于非项目组织成员，当前优先接受范围清楚、审查成本可控的 PR：

• 文档修正
• i18n 文案修正
• 明确且小范围的错别字、链接或描述修复
• 高质量、可复现、非 AI 批量生成的 bug fix
• 已在 Issue 中讨论，并被项目组采纳的功能、重构或行为调整

注意

较大的功能、架构、交互或目录结构改动，请先提交 Issue 讨论。未经过讨论且成本较高的 PR，项目组可能会直接关闭。

为什么？

这样做是为了保证贡献范围可控，避免贡献方向与开发组计划冲突，同时给高质量修复和已采纳提案留出空间。

我们的原则是：任何贡献对项目的价值都应大于审查它所需的工作量。

开始较大改动前，请先与项目组沟通。

开发组邀请会综合考虑：

• 工程判断和代码质量；
• 对项目结构、边界和维护成本的理解；
• 过往项目经验和问题定位能力；
• 沟通、协作和长期维护意愿；
• 持续贡献的稳定性和可靠性。

开发环境要求

依赖	版本
Node.js	22.12.0+
Rust	stable
pnpm	11.11.0

代码规范

Rust 代码规范

1. 格式化

   # 提交前最好运行
   cargo fmt --all

2. 代码检查

   # 建议通过所有 clippy 检查
   cargo clippy --workspace -- -D warnings

3. 命名规范

   • 文件名：使用 snake_case（如 server_manager.rs）
   • 函数名：使用 snake_case（如 get_server_list）
   • 结构体：使用 PascalCase（如 ServerInstance）
   • 常量：使用 SCREAMING_SNAKE_CASE（如 MAX_MEMORY）

4. 注释规范

   • 公共 API 建议留有文档注释（///）
   • 复杂逻辑建议添加行内注释（//）
   • 避免无意义的注释
   • 避免出现 Fuck the fmt 类似的语句

5. 错误处理

   • 使用 Result<T, String> 返回错误
   • 错误信息要清晰、用户友好
   • 避免使用 unwrap()，优先使用 ? 或 unwrap_or

前端代码规范

1. Vue 组件

   • 组件名使用 PascalCase（如 ServerCard.vue）
   • 使用 <script setup> 语法
   • Props 和 emits 必须定义类型

2. TypeScript

   • 启用严格模式
   • 避免使用 any，优先使用具体类型
   • 接口名使用 PascalCase

3. 样式

   • 使用 CSS 变量（var(--sl-*)）
   • 避免硬编码颜色值
   • 使用 scoped 样式

4. 格式化和检查

   # 格式化代码
   pnpm fmt
   
   # 检查格式
   pnpm fmt:check
   
   # Lint 检查
   pnpm lint
   
   # 自动修复 Lint 问题
   pnpm lint:fix

5. 变量引用检查

   • 声明变量时指定明确类型
   • 避免使用 any，使用具体类型
   • 使用 ref<T> 或 reactive 时指定泛型类型

UI 组件与图标

• 优先使用 Headless UI（Vue v1）与按需导入的图标库（如 Lucide）：

  • Headless UI（https://headlessui.com/v1/vue）提供无样式、可访问性的交互组件（如 Listbox、Disclosure、Dialog），推荐在需要复杂交互（弹出、折叠、可访问键盘支持）时优先复用它们，以减少手写 DOM 与键盘/ARIA 处理。
  • 图标使用可按需导入的组件库（如 Lucide：https://lucide.dev/icons/ 或示例图标 https://lucide.dev/icons/paint-roller?search=Palette），不要在项目中大量硬编码 <svg> 路径或重复 DOM。按需导入能保持包体积小并提高可维护性。
  • 推荐实践：使用 Headless UI 的 Listbox 替换自定义下拉/选择器；使用 Lucide 的图标组件（如 Palette / Paint-roller）替换硬编码图标。

  这样可减少冗余 DOM、统一可访问性处理，并把样式与行为分离，便于维护。

Git 工作流

分支命名

• feat/功能名 - 新功能
• fix/问题描述 - Bug 修复
• refactor/任务描述 - 重构
• chore/任务描述 - 杂项任务
• docs/文档说明 - 文档更新

Commit 建议

提交信息当前不再由本地 Hook 或 CI 强制校验，但仍建议保持清晰、可读，方便后续审查与回溯。

推荐使用简洁的约定式风格，例如：

feat(scope): 新增某项能力
fix: 修复某个具体问题
chore: 调整构建或目录结构

提交前建议自行运行必要检查，CI 会在 PR/推送时继续校验代码质量。

Pull Request 流程

1. Fork 项目并创建分支

   git checkout -b feat/your-feature

2. 开发并提交

   # 确保代码通过检查
   cargo fmt --all -- --check
   cargo clippy --workspace -- -D warnings
   pnpm fmt:check
   pnpm lint
   pnpm build
   
   # 提交变更
   git add .
   git commit -m "feat(scope): 你的功能描述"

3. 推送并创建 PR

   git push origin feat/your-feature

4. PR 标题和描述

   • 标题简洁明了（不超过 70 字符）
   • 描述包含：
     • 变更摘要
     • 测试方法
     • 相关 Issue（如有）

代码审查标准

建议满足

• ✅ 通过所有 CI 检查
• ✅ 代码格式正确（cargo fmt / oxfmt）
• ✅ 无 clippy 警告
• ✅ 无 oxlint 警告
• ✅ 功能完整且可用
• ✅ 无明显的性能问题

推荐满足

• 有适当的注释
• 有相关测试（如适用）
• 更新了相关文档
• UI 变更符合设计规范

常见问题

如何运行开发环境？

pnpm install
pnpm tauri:dev

如何构建发布版本？

pnpm tauri:build

但我们不推荐本地构建用来发布到 Release 中

如果你要按仓库当前的 GitHub Actions 流程发布正式版本或 Nightly 版本，请以仓库中的工作流配置为准。

Clippy 检查失败怎么办？

1. 查看具体警告信息
2. 运行 cargo clippy --fix 自动修复（部分问题）
3. 手动修复剩余问题
4. 如果某些警告不合理，可以使用 #[allow(clippy::...)] 标记

格式化检查失败怎么办？

尝试:

cargo fmt --all

获取帮助

• 在 Issue 中提问
• 联系维护者
• 查看项目文档

行为准则

• 尊重所有贡献者
• 保持友好和专业
• 接受建设性的反馈
• 帮助新手贡献者

---

再次感谢你的贡献！