LobeHub
LobeHub

代码风格与贡献指南

欢迎来到 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 来表示提交的类型或意图。以下是一个示例:

*.md
Markdown
📝 Update README with contribution guidelines

- Added section about code style preferences
- Included instructions for running tests
- Corrected typos and improved formatting

在这个示例中,📝 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 或请求合并前,请务必确保所有测试通过。

你可以在本地运行指定测试文件来验证:

*.sh
Shell
# 运行指定测试(不要运行 bun run test,全量测试耗时很长)
bunx vitest run --silent='passed-only' '[file-path]'

更多测试相关信息请参阅 测试指南。

Gitmoji 参考表

提交信息请使用以下 emoji 作为前缀:

Emoji代码类型说明触发发布?
✨:sparkles:feat新功能是
🐛:bug:fixBug 修复是
📝:memo:docs文档更新否
💄:lipstick:styleUI / 样式更改否
♻️:recycle:refactor代码重构否
✅:white_check_mark:test测试相关否
🔨:hammer:chore维护任务否
🚀:rocket:perf性能优化否
🌐:globe_with_meridians:i18n国际化否

如何贡献

1. Fork 并克隆仓库

在 GitHub 上 Fork lobehub/lobehub,然后克隆你的 Fork 到本地。

2. 创建分支

使用分支命名格式:用户名/类型/描述

*.sh
Shell
git checkout -b feat/add-voice-input
git checkout -b fix/message-duplication
git checkout -b docs/update-api-guide

3. 进行更改

遵循上方的代码风格指南。提交前运行代码检查:

*.sh
Shell
pnpm lint:ts       # TypeScript/JavaScript
pnpm lint:style    # CSS/样式
bun run type-check # 类型检查

4. 使用 gitmoji 提交

*.sh
Shell
git commit -m "✨ feat: 添加语音输入支持"
git commit -m "🐛 fix: 修复群聊消息重复问题"
git commit -m "📝 docs: 更新安装指南"

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 与上游代码

*.sh
Shell
git remote add upstream https://github.com/lobehub/lobehub.git
git fetch upstream
git rebase upstream/canary

贡献方向

  • 功能开发 — 查看 标注为 good first issue 的 Issue,找到适合新手的任务
  • Bug 修复 — 搜索标注为 bug 的开放 Issue
  • 文档改善 — 完善文档、修正错别字、添加示例
  • 测试补充 — 为缺少覆盖的代码路径添加测试
  • 翻译 — 添加缺失的 i18n 键(参见 i18n 指南)

感谢您遵循这些指导原则,它们有助于我们维护项目的质量和一致性。我们期待您的贡献!