代码风格与贡献指南
欢迎来到 LobeHub 的代码风格与贡献指南。本指南将帮助您理解我们的代码规范和贡献流程,确保代码的一致性和项目的顺利进行。
代码风格
在 LobeHub 中,我们使用 lobe-lint 提供的共享配置来统一代码风格。这些配置覆盖 Oxlint、Prettier、remarklint 和 stylelint,以确保我们的 JavaScript、Markdown 和 CSS 文件遵循相同的编码标准。
Oxlint
我们的项目使用 Oxlint 来检查 JavaScript 和 TypeScript 代码中的问题。您可以在项目根目录下找到 oxlint.config.mts 文件,其中包含了我们在 @lobehub/oxlint-config 之上的扩展和自定义规则。
为了与 Next.js 框架兼容,我们在配置中开启了 next 选项。此外,我们禁用了一些规则,以适应我们项目的特定需求。
Prettier
Prettier 负责代码格式化,以保证代码的一致性。您可以在 prettier.config.mjs 中找到我们的 Prettier 配置,它是从 @lobehub/prettier-config 导入的。
在保存文件时,建议您配置您的编辑器以自动运行 Prettier。
remarklint
对于 Markdown 文件,我们使用 remarklint 来确保文档格式的统一。您可以在项目中找到相应的配置文件。
stylelint
我们使用 stylelint 来规范 CSS 和 Less 文件的风格。在 stylelint 的配置文件中,我们基于 @lobehub/stylelint-config 进行了一些自定义规则的调整。StyleX 样式由 Oxlint 检查。
风格检查
你不需要手动运行这些检查,项目配置了 Git hooks 会在您提交代码时自动运行 lint-staged 检查你提交的文件是否符合以上规范。
贡献流程
LobeHub 采用 gitmoji 和 semantic release 作为我们的代码提交和发布流程。
Gitmoji
在提交代码时,请使用 gitmoji 来标注您的提交信息。这有助于其他贡献者快速理解您提交的内容和目的。
Gitmoji commit messages 使用特定的 emoji 来表示提交的类型或意图。以下是一个示例:
在这个示例中,📝 emoji 代表了文档的更新。提交信息清晰地描述了更改的内容,提供了具体的细节。
Semantic Release
我们使用 semantic release 来自动化版本控制和发布流程。当 PR 合并到主分支后,系统会根据提交信息中的 gitmoji 前缀自动判断是否需要发布新版本:
✨ feat和🐛 fix前缀的提交会触发新版本发布- 如果只是小修改不想发新版本,可以使用
💄 style或🔨 chore等前缀
Commitlint
为了确保提交信息的一致性,我们使用 commitlint 来检查提交信息格式。您可以在 commitlint.config.mjs 配置文件中找到相关规则。
在您提交代码之前,请确保您的提交信息遵循我们的规范。
测试
LobeHub 配置了完善的单元测试(Vitest)和 E2E 测试(Cucumber + Playwright),并通过 GitHub Actions CI 在每次 PR 提交时自动运行。提交 PR 或请求合并前,请务必确保所有测试通过。
你可以在本地运行指定测试文件来验证:
更多测试相关信息请参阅 测试指南。
Gitmoji 参考表
提交信息请使用以下 emoji 作为前缀:
| Emoji | 代码 | 类型 | 说明 | 触发发布? |
|---|---|---|---|---|
| ✨ | :sparkles: | feat | 新功能 | 是 |
| 🐛 | :bug: | fix | Bug 修复 | 是 |
| 📝 | :memo: | docs | 文档更新 | 否 |
| 💄 | :lipstick: | style | UI / 样式更改 | 否 |
| ♻️ | :recycle: | refactor | 代码重构 | 否 |
| ✅ | :white_check_mark: | test | 测试相关 | 否 |
| 🔨 | :hammer: | chore | 维护任务 | 否 |
| 🚀 | :rocket: | perf | 性能优化 | 否 |
| 🌐 | :globe_with_meridians: | i18n | 国际化 | 否 |
如何贡献
1. Fork 并克隆仓库
在 GitHub 上 Fork lobehub/lobehub,然后克隆你的 Fork 到本地。
2. 创建分支
使用分支命名格式:用户名/类型/描述
3. 进行更改
遵循上方的代码风格指南。提交前运行代码检查:
4. 使用 gitmoji 提交
5. 创建 Pull Request
PR 的目标分支必须是 canary,而非 main。canary 是当前活跃的开发分支,向 main 发起的 PR
会被重定向。
请使用 .github/PULL_REQUEST_TEMPLATE.md 中的 PR 模板:
- Human — 改了什么、截图、如何测试、验收记录,以及关联 issue(
Fixes #123、Fixes LOBE-xxx) - AI — 人写的改动删掉这一节。Agent 写的改动,如果作者是外部 collaborator 或其他外部贡献者,模板里的注释指令会要求这个 agent 填写 harness、模型、thinking level,以及这次会话里的全部 user prompt(按顺序保留)。发布前由作者审阅这段文字,敏感内容打码。lobehub organization 的正式成员删掉这一节。
PR 标题中带有 ✨ feat: 或 🐛 fix: 前缀时将自动触发新版本发布。 不需要发布新版本的改动请使用其他前缀。
6. 代码审查
每次 PR 会自动运行:ESLint、TypeScript 类型检查、Vitest 单元测试、E2E 测试和构建验证。请根据审查意见向同一分支推送新的提交。
同步 Fork 与上游代码
贡献方向
- 功能开发 — 查看 标注为
good first issue的 Issue,找到适合新手的任务 - Bug 修复 — 搜索标注为
bug的开放 Issue - 文档改善 — 完善文档、修正错别字、添加示例
- 测试补充 — 为缺少覆盖的代码路径添加测试
- 翻译 — 添加缺失的 i18n 键(参见 i18n 指南)
感谢您遵循这些指导原则,它们有助于我们维护项目的质量和一致性。我们期待您的贡献!