# 贡献指南（Contributing Guide）

感谢你愿意为本项目做出贡献！为了保证项目质量、可维护性以及 Review 体验，请在提交 Issue 或 Pull Request 前认真阅读并遵守以下规范。

---

## 一、基本原则

### 1. 一个 PR 只做一件事（Single Responsibility）

* **不要在一个 PR 中同时提交多个不相关的功能或修改**。
* 功能新增、Bug 修复、重构、格式化、文档更新应尽量拆分为**独立 PR**。
* 如果多个提交逻辑上强相关，请在 PR 描述中清楚说明原因。

✅ 好例子：

* PR A：修复某个崩溃 Bug
* PR B：为该功能新增配置项

❌ 不好例子：

* 一个 PR 同时包含：新功能 + UI 调整 + 日志语言替换 + 代码格式化

---

### 2. 不要进行“顺手式修改”

* **不要修改与本 PR 目标无关的代码**，包括但不限于：

  * 批量重命名变量
  * 代码风格调整
  * 无关的注释修改
  * IDE 自动格式化导致的大面积 diff

这类修改会严重增加 Review 成本，也容易引入隐藏问题。

---

## 二、语言与本地化规范（非常重要）

### 1. 不要擅自替换项目的默认语言

* 本项目已有既定的**默认语言**（如中文或英文）。
* **禁止在未沟通的情况下，将现有文本（UI、日志、注释、文档等）整体替换为其他语言**。
* 这类 PR **将直接被拒绝合并**。

### 2. 正确的多语言贡献方式

如果你希望为项目增加新的语言支持：

* 新增 **独立的语言文件 / 文档**（如 `README_KR.md`、`i18n/ko_KR.json`）
* 不要修改或覆盖原有语言内容
* 不要在代码中硬编码其他语言字符串

---

## 三、代码修改规范

### 1. 避免“反向修改（Reverse Changes）”

* 提交前请仔细检查 diff，确保：

  * 没有误删已有功能
  * 没有回退历史已修复的问题
* 若在解决冲突时产生了大范围反向修改，请**停止提交并重新整理 commit**。

---

### 2. 重构需谨慎

* 重构（Refactor）应：

  * **不改变对外行为**，除非提前说明
  * 单独作为一个 PR 提交
* 不要在功能 PR 中夹带重构代码。

---

### 3. 性能 / 架构调整需先讨论

* 涉及以下内容时，请**先开 Issue 讨论**：

  * 语言迁移（如 Python → C++ / C#）
  * 大规模架构重构
  * 替换核心技术栈（GUI、图像识别、自动化方案等）

原因：

* 技术选型通常与项目定位、维护成本、社区现状强相关
* 未讨论的重构 PR 通常无法直接合并

---

## 四、提交质量要求

### 1. 确保代码可运行

* PR 提交前请自行验证：

  * 项目可以正常启动
  * 新增功能能正常使用
  * 不引入明显性能回退或卡顿问题

---

### 2. 提交信息（Commit Message）规范

* 使用清晰、可读的提交信息
* 推荐格式：

```
<type>: <简要说明>

- 修改点 1
- 修改点 2
```

常见 type：

* `fix`：Bug 修复
* `feat`：新功能
* `refactor`：重构（无功能变化）
* `docs`：文档更新
* `chore`：构建 / 工具链相关

---

## 五、Issue 使用规范

### 1. Issue ≠ 个人需求清单

* Issue 应：

  * 描述清楚问题或需求背景
  * 说明使用场景和实际痛点
* 请避免：

  * 只为个人极小众使用场景提需求
  * 带有情绪化、阴阳怪气或攻击性表述

---

### 2. 建议类 Issue

* 架构、性能、技术选型建议欢迎讨论
* 但请接受：

  * 建议不一定会被采纳
  * 维护者有最终决策权

---

## 六、Review 与沟通

### 1. 尊重 Review 意见

* Review 的目标是：

  * 提升代码质量
  * 降低长期维护成本
* 请理性讨论技术问题，避免情绪化回应。

---

### 2. PR 可能被关闭的常见原因

* 一个 PR 包含过多不相关修改
* 大规模替换语言 / 文本
* 未讨论的架构级重构
* 代码质量明显不足，且作者不愿配合修改

---

## 七、维护者说明

* 本项目为维护者主导的开源项目
* 贡献是**欢迎的，但不是义务合并**
* 是否合并 PR，将综合考虑：

  * 项目方向
  * 维护成本
  * 社区影响

感谢你的理解与尊重 ❤️

---

如果你对贡献流程有任何疑问，欢迎先通过 Issue 与维护者沟通。
