Contributing Guide Expert

贡献指南专家

Эксперт по документации для open source contributors.

开源项目贡献者文档专家。

Структура CONTRIBUTING.md

CONTRIBUTING.md结构

markdown

undefined

markdown

undefined

Contributing to Project Name

Thank you for your interest in contributing! 🎉

Quick Start Section

快速入门章节

markdown

undefined

markdown

undefined

Quick Start

Fork the repository

Clone your fork:

bash

git clone https://github.com/YOUR_USERNAME/project-name.git
cd project-name

Install dependencies:
bash
```
npm install
```

Create a branch:

bash

git checkout -b feature/your-feature-name

Make changes and test:
bash
```
npm test
```
Submit a PR!

undefined

Fork the repository

Clone your fork:

bash

git clone https://github.com/YOUR_USERNAME/project-name.git
cd project-name

Install dependencies:
bash
```
npm install
```

Create a branch:

bash

git checkout -b feature/your-feature-name

Make changes and test:
bash
```
npm test
```
Submit a PR!

undefined

Development Environment

开发环境

markdown

undefined

markdown

undefined

Development Setup

Prerequisites

Node.js 18+ (download)
npm 8+ or yarn 1.22+
Git 2.28+
Docker (optional, for integration tests)

Node.js 18+ (download)
npm 8+ or yarn 1.22+
Git 2.28+
Docker (optional, for integration tests)

Installation

bash

undefined

bash

undefined

Clone repository

git clone https://github.com/org/project.git cd project

Install dependencies

npm install

Copy environment file

cp .env.example .env

Run setup script

npm run setup

Verify installation

npm test

undefined

npm test

undefined

Available Scripts

可用脚本

Command	Description
`npm run dev`	Start development server
`npm test`	Run all tests
`npm run test:watch`	Run tests in watch mode
`npm run lint`	Run ESLint
`npm run lint:fix`	Fix linting issues
`npm run typecheck`	Run TypeScript checks
`npm run build`	Build for production

undefined

Command	Description
`npm run dev`	Start development server
`npm test`	Run all tests
`npm run test:watch`	Run tests in watch mode
`npm run lint`	Run ESLint
`npm run lint:fix`	Fix linting issues
`npm run typecheck`	Run TypeScript checks
`npm run build`	Build for production

undefined

Git Workflow

Git工作流

markdown

undefined

markdown

undefined

Git Workflow

Branch Naming Convention

分支命名规范

<type>/<short-description>

Types:

```
feature/
```
- New features
```
fix/
```
- Bug fixes
```
docs/
```
- Documentation only
```
refactor/
```
- Code refactoring
```
test/
```
- Adding tests
```
chore/
```
- Maintenance tasks

Examples:

```
feature/user-authentication
```
```
fix/login-redirect-loop
```
```
docs/api-examples
```

<type>/<short-description>

类型:

```
feature/
```
- 新功能
```
fix/
```
- Bug修复
```
docs/
```
- 仅文档更新
```
refactor/
```
- 代码重构
```
test/
```
- 添加测试
```
chore/
```
- 维护任务

示例:

```
feature/user-authentication
```
```
fix/login-redirect-loop
```
```
docs/api-examples
```

Commit Messages

提交信息

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

```
feat
```
: New feature
```
fix
```
: Bug fix
```
docs
```
: Documentation
```
style
```
: Formatting (no code change)
```
refactor
```
: Code refactoring
```
test
```
: Adding tests
```
chore
```
: Maintenance

Examples:

feat(auth): add OAuth2 support
fix(api): handle null response from server
docs(readme): update installation steps

undefined

我们遵循Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

类型:

```
feat
```
: 新功能
```
fix
```
: Bug修复
```
docs
```
: 文档更新
```
style
```
: 格式调整（无代码逻辑变更）
```
refactor
```
: 代码重构
```
test
```
: 添加测试
```
chore
```
: 维护任务

示例:

feat(auth): add OAuth2 support
fix(api): handle null response from server
docs(readme): update installation steps

undefined

Pull Request Template

拉取请求模板

markdown

undefined

markdown

undefined

Pull Request Guidelines

Before Submitting

提交前检查

I have read the Contributing Guide
My code follows the project's style guidelines
I have performed a self-review
I have added tests for my changes
All new and existing tests pass
I have updated documentation if needed
My commits follow conventional commit format

我已阅读贡献指南
我的代码符合项目风格规范
我已完成自我审查
我为变更添加了测试
所有新测试和现有测试均通过
必要时我已更新文档
我的提交信息符合规范提交格式

PR Template

PR模板

markdown

undefined

markdown

undefined

Description

描述

Type of Change

变更类型

Bug fix (non-breaking change)
New feature (non-breaking change)
Breaking change
Documentation update

Bug修复（非破坏性变更）
新功能（非破坏性变更）
破坏性变更
文档更新

How Has This Been Tested?

测试方式

Screenshots (if applicable)

截图（如适用）

Checklist

检查清单

Tests pass
Lint passes
Documentation updated

undefined

测试通过
代码检查通过
文档已更新

undefined

Issue Templates

问题模板

Bug Report

Bug报告

markdown

---
name: Bug Report
about: Report a bug to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---

markdown

---
name: Bug Report
about: Report a bug to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---

Bug Description

Bug描述

Steps to Reproduce

复现步骤

Go to '...'
Click on '...'
See error

Go to '...'
Click on '...'
See error

Expected Behavior

预期行为

Actual Behavior

实际行为

Environment

环境信息

OS: [e.g., macOS 14.0]
Node version: [e.g., 18.17.0]
Project version: [e.g., 1.2.3]

OS: [e.g., macOS 14.0]
Node version: [e.g., 18.17.0]
Project version: [e.g., 1.2.3]

Screenshots

截图

Additional Context

补充信息

undefined

undefined

Feature Request

功能请求

markdown

---
name: Feature Request
about: Suggest a new feature
title: '[FEATURE] '
labels: enhancement
assignees: ''
---

markdown

---
name: Feature Request
about: Suggest a new feature
title: '[FEATURE] '
labels: enhancement
assignees: ''
---

Problem Statement

问题陈述

Proposed Solution

提议的解决方案

Alternatives Considered

考虑过的替代方案

Additional Context

补充信息

undefined

undefined

Code Style Guide

代码风格指南

markdown

undefined

markdown

undefined

Style Guide

风格指南

General Principles

通用原则

Write self-documenting code
Prefer explicit over implicit
Keep functions small and focused
DRY (Don't Repeat Yourself)

编写自文档化代码
优先显式而非隐式
保持函数短小且聚焦
DRY（避免重复代码）

TypeScript/JavaScript

typescript

// ✅ Good
function calculateTotalPrice(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// ❌ Bad
function calc(i: any[]): any {
  let t = 0;
  for (let x of i) t += x.p * x.q;
  return t;
}

typescript

// ✅ 良好示例
function calculateTotalPrice(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// ❌ 不良示例
function calc(i: any[]): any {
  let t = 0;
  for (let x of i) t += x.p * x.q;
  return t;
}

Naming Conventions

命名规范

Type	Convention	Example
Variables	camelCase	`userName`
Functions	camelCase	`getUserById`
Classes	PascalCase	`UserService`
Constants	UPPER_SNAKE	`MAX_RETRIES`
Files	kebab-case	`user-service.ts`
Interfaces	PascalCase + I prefix	`IUserService`

类型	规范	示例
变量	camelCase	`userName`
函数	camelCase	`getUserById`
类	PascalCase	`UserService`
常量	UPPER_SNAKE	`MAX_RETRIES`
文件	kebab-case	`user-service.ts`
接口	PascalCase + I前缀	`IUserService`

File Structure

文件结构

src/
├── components/     # UI components
├── hooks/          # Custom React hooks
├── services/       # Business logic
├── utils/          # Helper functions
├── types/          # TypeScript types
└── __tests__/      # Test files

undefined

src/
├── components/     # UI组件
├── hooks/          # 自定义React hooks
├── services/       # 业务逻辑
├── utils/          # 辅助函数
├── types/          # TypeScript类型定义
└── __tests__/      # 测试文件

undefined

Code Review Process

代码审查流程

markdown

undefined

markdown

undefined

Code Review

代码审查

Review Checklist

审查检查清单

Response Times

响应时间

First response: within 48 hours
Follow-up reviews: within 24 hours
Merge after approval: within 24 hours

首次响应：48小时内
后续审查：24小时内
批准后合并：24小时内

Approval Requirements

批准要求

1 maintainer approval required
All CI checks must pass
No unresolved conversations

undefined

需要1位维护者批准
所有CI检查必须通过
无不解决的讨论

undefined

Pre-commit Hooks

提交前钩子

json

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md}": [
      "prettier --write"
    ]
  }
}

json

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md}": [
      "prettier --write"
    ]
  }
}

Recognition Program

贡献者认可计划

markdown

undefined

markdown

undefined

Recognition

认可

Contributors

贡献者

All contributors are added to our CONTRIBUTORS.md file.

所有贡献者将被添加到我们的CONTRIBUTORS.md文件中。

Badges

徽章

Badge	Criteria
🥇 First Contribution	Merged first PR
🔥 Frequent Contributor	10+ merged PRs
📚 Documentation Hero	5+ docs PRs
🐛 Bug Hunter	5+ bug fixes
⭐ Core Contributor	Significant impact

徽章	获得条件
🥇 首次贡献	合并首个PR
🔥 频繁贡献者	合并10个以上PR
📚 文档英雄	提交5个以上文档PR
🐛 Bug猎手	修复5个以上Bug
⭐ 核心贡献者	对项目有重大影响

Rewards

奖励

Stickers and swag for active contributors
Shoutouts in release notes
Conference ticket opportunities
LinkedIn recommendations

undefined

为活跃贡献者提供贴纸和周边
在发布说明中提及
会议门票机会
LinkedIn推荐

undefined

Community Guidelines

社区指南

markdown

undefined

markdown

undefined

Community

社区

Communication Channels

沟通渠道

Discord: Join our server
GitHub Discussions: For questions and ideas
Twitter: @project

Discord: 加入我们的服务器
GitHub Discussions: 用于提问和交流想法
Twitter: @project

Response Time Expectations

响应时间预期

Issues: 48 hours
PRs: 72 hours
Questions: 24-48 hours

问题：48小时内
PR：72小时内
咨询：24-48小时内

Getting Help

获取帮助

Check existing issues and discussions
Read the documentation
Ask in Discord #help channel
Create a GitHub Discussion

查看现有问题和讨论
阅读文档
在Discord的#help频道提问
创建GitHub Discussion

Code of Conduct

行为准则

We follow the Contributor Covenant. Be respectful, inclusive, and constructive.

undefined

我们遵循Contributor Covenant。请保持尊重、包容和建设性。

undefined

Лучшие практики

最佳实践

Progressive disclosure — от простого к сложному
Clear examples — реальные примеры кода
Up-to-date — обновляйте при изменениях
Welcoming tone — дружелюбный язык
Multiple entry points — для разных типов contributions
Automated checks — CI для валидации PR

渐进式披露 — 从简单到复杂
清晰示例 — 真实代码示例
实时更新 — 随变更同步更新
友好语气 — 使用亲切的语言
多入口点 — 适配不同类型的贡献内容
自动化检查 — 用CI验证PR

contributing-guide

Original

Translation

Contributing Guide Expert

贡献指南专家

Структура CONTRIBUTING.md

CONTRIBUTING.md结构

Contributing to Project Name

Contributing to Project Name

Table of Contents

Table of Contents

Quick Start Section

快速入门章节

Quick Start

Quick Start

Development Environment

开发环境

Development Setup

Development Setup

Prerequisites

Prerequisites

Installation

Installation

Clone repository

Clone repository

Install dependencies

Install dependencies

Copy environment file

Copy environment file

Run setup script

Run setup script

Verify installation

Verify installation

Available Scripts

可用脚本

Git Workflow

Git工作流

Git Workflow

Git Workflow

Branch Naming Convention

分支命名规范

Commit Messages

提交信息

Pull Request Template

拉取请求模板

Pull Request Guidelines

Pull Request Guidelines

Before Submitting

提交前检查

PR Template

PR模板

Description

描述

Type of Change

变更类型

How Has This Been Tested?

测试方式

Screenshots (if applicable)

截图（如适用）

Checklist

检查清单

Issue Templates

问题模板

Bug Report

Bug报告

Bug Description

Bug描述

Steps to Reproduce

复现步骤

Expected Behavior

预期行为

Actual Behavior

实际行为

Environment

环境信息

Screenshots

截图

Additional Context

补充信息

Feature Request