lobehub__lobehub/docs/development/basic/contributing-guidelines.mdx

---
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 `eslint.config.mjs` flat config 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 `prettier.config.mjs`, 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 Git hooks 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 `commitlint.config.mjs` 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!