mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-27 13:29:15 +07:00
198 lines
7.6 KiB
Plaintext
198 lines
7.6 KiB
Plaintext
---
|
|
title: Code Style and Contribution Guidelines
|
|
description: >-
|
|
Learn about LobeHub's code style and contribution process for consistent
|
|
coding.
|
|
tags:
|
|
- Code Style
|
|
- Contribution Guidelines
|
|
- LobeHub
|
|
- ESLint
|
|
- Prettier
|
|
---
|
|
|
|
# Code Style and Contribution Guidelines
|
|
|
|
Welcome to the Code Style and Contribution Guidelines for LobeHub. This guide will help you understand our code standards and contribution process, ensuring code consistency and smooth project progression.
|
|
|
|
## Code Style
|
|
|
|
In LobeHub, we use the [@lobehub/lint](https://github.com/lobehub/lobe-lint) package to maintain a unified code style. This package incorporates configurations for `ESLint`, `Prettier`, `remarklint`, and `stylelint` to ensure that our JavaScript, Markdown, and CSS files adhere to the same coding standards.
|
|
|
|
### ESLint
|
|
|
|
We use ESLint to check for issues in our JavaScript code. You can find the `.eslintrc.js` file in the project's root directory, which contains our extensions and custom rules for the ESLint configuration of `@lobehub/lint`.
|
|
|
|
To ensure your code aligns with the project's standards, run ESLint before committing your code.
|
|
|
|
### Prettier
|
|
|
|
Prettier is responsible for code formatting to maintain consistency. Our Prettier configuration can be found in `.prettierrc.js`, imported from `@lobehub/lint`.
|
|
|
|
It's recommended to configure your editor to run Prettier automatically when saving files.
|
|
|
|
### remarklint
|
|
|
|
For Markdown files, we use remarklint to ensure consistent document formatting. You can find the corresponding configuration file in the project.
|
|
|
|
### stylelint
|
|
|
|
We utilize stylelint to standardize the style of our CSS code. In the configuration file for stylelint, we have made some custom rule adjustments based on `@lobehub/lint` configuration.
|
|
|
|
### Style Checking
|
|
|
|
You don't need to manually run these checks. The project is configured with husky to automatically run lint-staged when you commit code, which will check if your committed files comply with the above standards.
|
|
|
|
## Contribution Process
|
|
|
|
LobeHub follows the gitmoji and semantic release as our code submission and release process.
|
|
|
|
### Gitmoji
|
|
|
|
When committing code, please use gitmoji to label your commit messages. This helps other contributors quickly understand the content and purpose of your submission.
|
|
|
|
Gitmoji commit messages use specific emojis to represent the type or intent of the commit. Here's an example:
|
|
|
|
```markdown
|
|
📝 Update README with contribution guidelines
|
|
|
|
- Added section about code style preferences
|
|
- Included instructions for running tests
|
|
- Corrected typos and improved formatting
|
|
```
|
|
|
|
In this example, the 📝 emoji represents a documentation update. The commit message clearly describes the changes and provides specific details.
|
|
|
|
### Semantic Release
|
|
|
|
We use semantic release to automate version control and release processes. When a PR is merged into the main branch, the system automatically determines whether to publish a new version based on the gitmoji prefix in commit messages:
|
|
|
|
- Commits with `✨ feat` or `🐛 fix` prefixes will **trigger a new release**
|
|
- For minor changes that don't need a release, use prefixes like `💄 style` or `🔨 chore`
|
|
|
|
### Commitlint
|
|
|
|
To ensure consistency in commit messages, we use `commitlint` to check the format of commit messages. You can find the relevant rules in the `.commitlintrc.js` configuration file.
|
|
|
|
Before committing your code, ensure that your commit messages adhere to our standards.
|
|
|
|
### Testing
|
|
|
|
LobeHub has comprehensive unit tests (Vitest) and E2E tests (Cucumber + Playwright), which run automatically via GitHub Actions CI on every PR. Before submitting a PR or requesting a merge, make sure all tests pass.
|
|
|
|
You can run specific test files locally to verify:
|
|
|
|
```bash
|
|
# Run specific test (never run bun run test — full suite is very slow)
|
|
bunx vitest run --silent='passed-only' '[file-path]'
|
|
```
|
|
|
|
For more testing details, see the [Testing Guide](/docs/development/basic/test).
|
|
|
|
### Gitmoji Reference
|
|
|
|
Use the following emojis to prefix your commit messages:
|
|
|
|
| Emoji | Code | Type | Description | Triggers Release? |
|
|
| ----- | ------------------------ | -------- | ------------------------ | ----------------- |
|
|
| ✨ | `:sparkles:` | feat | New feature | Yes |
|
|
| 🐛 | `:bug:` | fix | Bug fix | Yes |
|
|
| 📝 | `:memo:` | docs | Documentation | No |
|
|
| 💄 | `:lipstick:` | style | UI/styling changes | No |
|
|
| ♻️ | `:recycle:` | refactor | Code refactoring | No |
|
|
| ✅ | `:white_check_mark:` | test | Tests | No |
|
|
| 🔨 | `:hammer:` | chore | Maintenance tasks | No |
|
|
| 🚀 | `:rocket:` | perf | Performance improvements | No |
|
|
| 🌐 | `:globe_with_meridians:` | i18n | Internationalization | No |
|
|
|
|
### How to Contribute
|
|
|
|
**1. Fork and clone the repository**
|
|
|
|
Fork [lobehub/lobehub](https://github.com/lobehub/lobehub) on GitHub, then clone your fork locally.
|
|
|
|
**2. Create a branch**
|
|
|
|
Use the branch naming format: `username/type/description`
|
|
|
|
```bash
|
|
git checkout -b feat/add-voice-input
|
|
git checkout -b fix/message-duplication
|
|
git checkout -b docs/update-api-guide
|
|
```
|
|
|
|
**3. Make changes**
|
|
|
|
Follow the [code style guidelines](/docs/development/basic/contributing-guidelines#code-style) above. Run linters before committing:
|
|
|
|
```bash
|
|
pnpm lint:ts # TypeScript/JavaScript
|
|
pnpm lint:style # CSS/styles
|
|
bun run type-check # Type checking
|
|
```
|
|
|
|
**4. Commit with gitmoji**
|
|
|
|
```bash
|
|
git commit -m "✨ feat: add voice input support"
|
|
git commit -m "🐛 fix: resolve message duplication in group chat"
|
|
git commit -m "📝 docs: update installation guide"
|
|
```
|
|
|
|
**5. Open a Pull Request**
|
|
|
|
<Callout type={'warning'}>
|
|
Always target the **`canary`** branch — not `main`. `canary` is the active development branch. PRs
|
|
to `main` will be redirected.
|
|
</Callout>
|
|
|
|
Fill out the PR template in `.github/PULL_REQUEST_TEMPLATE.md`:
|
|
|
|
```markdown
|
|
## Description
|
|
|
|
Clear description of what this PR does.
|
|
|
|
## Type of Change
|
|
|
|
- [ ] ✨ New feature
|
|
- [ ] 🐛 Bug fix
|
|
- [ ] 📝 Documentation
|
|
- [ ] ♻️ Refactoring
|
|
|
|
## Checklist
|
|
|
|
- [ ] Code follows project style guidelines
|
|
- [ ] Tests added/updated
|
|
- [ ] Documentation updated
|
|
- [ ] All tests pass
|
|
|
|
## Related Issues
|
|
|
|
Fixes #123
|
|
```
|
|
|
|
**PR titles with `✨ feat:` or `🐛 fix:` automatically trigger a new release.** Use other prefixes for changes that don't need a release.
|
|
|
|
**6. Code review**
|
|
|
|
Automated checks run on every PR: ESLint, TypeScript type check, Vitest unit tests, E2E tests, and build. Address review feedback by pushing additional commits to the same branch.
|
|
|
|
### Syncing Your Fork with Upstream
|
|
|
|
```bash
|
|
git remote add upstream https://github.com/lobehub/lobehub.git
|
|
git fetch upstream
|
|
git rebase upstream/canary
|
|
```
|
|
|
|
### Ways to Contribute
|
|
|
|
- **Features** — Check [issues labeled `good first issue`](https://github.com/lobehub/lobehub/issues?q=is%3Aissue+label%3A%22good+first+issue%22) to find beginner-friendly tasks
|
|
- **Bug fixes** — Search open issues labeled `bug`
|
|
- **Documentation** — Improve docs, fix typos, add examples
|
|
- **Testing** — Add test coverage for uncovered code paths
|
|
- **Translations** — Add missing i18n keys (see [i18n guide](/docs/development/internationalization/internationalization-implementation))
|
|
|
|
Thank you for following these guidelines, as they help us maintain the quality and consistency of the project. We look forward to your contributions!
|