代码风格与贡献指南

欢迎来到 LobeHub 的代码风格与贡献指南。本指南将帮助您理解我们的代码规范和贡献流程，确保代码的一致性和项目的顺利进行。

代码风格

在 LobeHub 中，我们使用 @lobehub/lint 程序包来统一代码风格。该程序包内置了 ESLint、Prettier、remarklint 和 stylelint 的配置，以确保我们的 JavaScript、Markdown 和 CSS 文件遵循相同的编码标准。

ESLint

我们的项目使用 ESLint 来检查 JavaScript 代码中的问题。您可以在项目根目录下找到 .eslintrc.js 文件，其中包含了我们对 @lobehub/lint 的 ESLint 配置的扩展和自定义规则。

为了与 Next.js 框架兼容，我们在配置中添加了 plugin:@next/next/recommended。此外，我们禁用了一些规则，以适应我们项目的特定需求。

Prettier

Prettier 负责代码格式化，以保证代码的一致性。您可以在 .prettierrc.js 中找到我们的 Prettier 配置，它是从 @lobehub/lint 导入的。

在保存文件时，建议您配置您的编辑器以自动运行 Prettier。

remarklint

对于 Markdown 文件，我们使用 remarklint 来确保文档格式的统一。您可以在项目中找到相应的配置文件。

stylelint

我们使用 stylelint 来规范 CSS 代码的风格。在 stylelint 的配置文件中，我们基于 @lobehub/lint 的配置进行了一些自定义规则的调整。

风格检查

你不需要手动运行这些检查，项目配置了 husky 会在您提交代码时自动运行 lint-staged 检查你提交的文件是否符合以上规范。

贡献流程

LobeHub 采用 gitmoji 和 semantic release 作为我们的代码提交和发布流程。

Gitmoji

在提交代码时，请使用 gitmoji 来标注您的提交信息。这有助于其他贡献者快速理解您提交的内容和目的。

Gitmoji commit messages 使用特定的 emoji 来表示提交的类型或意图。以下是一个示例：

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 来检查提交信息格式。您可以在 .commitlintrc.js 配置文件中找到相关规则。

在您提交代码之前，请确保您的提交信息遵循我们的规范。

测试

LobeHub 配置了完善的单元测试（Vitest）和 E2E 测试（Cucumber + Playwright），并通过 GitHub Actions CI 在每次 PR 提交时自动运行。提交 PR 或请求合并前，请务必确保所有测试通过。

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

bash

# 运行指定测试（不要运行 bun run test，全量测试耗时很长）
bunx vitest run --silent='passed-only' '[file-path]'

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

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. 创建分支

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

bash

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

3. 进行更改

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

bash

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

4. 使用 gitmoji 提交

bash

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

5. 创建 Pull Request

<Callout type={'warning'}> PR 的目标分支必须是 canary，而非 main。canary 是当前活跃的开发分支，向 main 发起的 PR 会被重定向。 </Callout>

请使用 .github/PULL_REQUEST_TEMPLATE.md 中的 PR 模板：

markdown

## Description

清晰描述此 PR 的改动内容。

## Type of Change

- [ ] ✨ 新功能
- [ ] 🐛 Bug 修复
- [ ] 📝 文档
- [ ] ♻️ 重构

## Checklist

- [ ] 代码符合项目风格指南
- [ ] 已添加/更新测试
- [ ] 已更新文档
- [ ] 所有测试通过

## Related Issues

Fixes #123

PR 标题中带有 ✨ feat: 或 🐛 fix: 前缀时将自动触发新版本发布。 不需要发布新版本的改动请使用其他前缀。

6. 代码审查

每次 PR 会自动运行：ESLint、TypeScript 类型检查、Vitest 单元测试、E2E 测试和构建验证。请根据审查意见向同一分支推送新的提交。

同步 Fork 与上游代码

bash

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 指南）

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