签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -1,188 +1,47 @@
-# K. 贡献指南
+# L. 贡献指南

-:::tip 说明
-感谢你对本项目的关注！本文档介绍如何参与项目贡献，包括代码提交、Issue 反馈、PR 流程等。
+:::tip 概述
+欢迎贡献代码、报告问题与完善文档。本页给出参与方式与质量要求。
 :::

-## 开发环境搭建
+## 参与方式

-1. Fork 项目到自己的 Gitee/GitHub 账号
-2. 从[官方网站](https://www.rxthink.cn)下载授权源码包
-3. 参考 [开发环境准备](/zh/quickstart/environment.html) 安装依赖
-4. 创建开发分支：`git checkout -b feature/your-feature`
+| 方式 | 说明 |
+|---|---|
+| 报告问题 | 提 Issue：环境、复现步骤、期望/实际行为、日志（脱敏） |
+| 提交修复 | Fork → 分支 → PR，关联 Issue 编号 |
+| 功能建议 | Issue 讨论先行，大改动先对齐方案再动手 |
+| 文档完善 | 文档站与代码同仓，PR 同样适用本指南 |

-## 分支策略
+## 代码要求

-| 分支 | 用途 | 说明 |
-|------|------|------|
-| `master` | 主分支 | 稳定版本，只接受 PR 合并 |
-| `feature/*` | 功能分支 | 新功能开发，完成后合并到 master |
-| `hotfix/*` | 修复分支 | 紧急修复，从 master 拉取，修复后合并回 master |
-
-```text
-master ────●───────●───────●───── (发布)
-             ↑           ↑
-feature/a ──●──●   feature/b ──●──●
-```
-
-## Commit 规范
-
-提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式：
-
-```html
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-### Type 类型
-
-| 类型 | 说明 | 示例 |
-|------|------|------|
-| `feat` | 新功能 | `feat(user): 添加用户导入功能` |
-| `fix` | 修复 bug | `fix(auth): 修复 Token 过期未返回 401` |
-| `docs` | 文档更新 | `docs: 更新部署文档` |
-| `style` | 代码格式（不影响功能） | `style: 格式化代码` |
-| `refactor` | 重构（非新功能非修复） | `refactor(service): 重构分页查询逻辑` |
-| `perf` | 性能优化 | `perf(query): 优化 N+1 查询` |
-| `test` | 测试相关 | `test: 添加用户模块单元测试` |
-| `chore` | 构建/工具相关 | `chore: 更新依赖版本` |
-
-### 示例
-
-```text
-feat(generator): 支持树形表格模板生成
-
- 新增 ui2/ 树形模板目录
- 自动识别 parent_id/pid 字段
- 支持 el-tree-select 组件
-
-Closes #123
-```
-
-## PR 流程
-
-### 1. 准备工作
+- 遵守 [第 12 章 规范标准](/zh/standards/api-response.html)：数据访问铁律、模块规约、信封与分页契约
+- 提交信息符合 [12.5 Git 提交规范](/zh/standards/git.html)
+- PR 前本地通过：

 ```bash
-# 1. 同步上游代码
-git fetch upstream
-git rebase upstream/master
-
-# 2. 创建功能分支
-git checkout -b feature/your-feature
-
-# 3. 开发并提交
-git add .
-git commit -m "feat(xxx): 添加xxx功能"
-
-# 4. 推送到自己的仓库
-git push origin feature/your-feature
+make check              # 后端：fmt + vet + test-short + check-config
+cd ui && pnpm type:check && pnpm lint:eslint   # 前端
 ```

-### 2. 创建 PR
+- 新功能附测试或说明不测原因；修 bug 附复现描述
+- 生成器模板改动与产物同提交

- 标题简洁明了，遵循 Commit 规范
- 描述清楚做了什么、为什么做、怎么测试的
- 关联相关的 Issue（如 `Closes #123`）
- 附上截图或 GIF（如有 UI 变更）
+## PR 审查关注点

-### 3. PR 模板
+见 [12.7 代码审查清单](/zh/standards/code-review.html)。阻塞项：数据访问红线、契约稳定性、错误处理、权限与敏感信息、配置一致性。

-```markdown
-## 变更说明
+## 文档贡献

-简要描述本次变更的内容。
-
-## 变更类型
-
- [ ] 新功能 (feat)
- [ ] Bug 修复 (fix)
- [ ] 文档更新 (docs)
- [ ] 代码重构 (refactor)
- [ ] 性能优化 (perf)
-
-## 测试情况
-
- [ ] 本地测试通过
- [ ] 添加了单元测试
- [ ] 手动验证了功能
-
-## 关联 Issue
-
-Closes #xxx
-```
-
-### 4. 代码审查
-
- 至少一人审查通过后方可合并
- 审查关注：正确性 > 安全性 > 可维护性 > 性能
- 参考 [代码审查清单](/zh/standards/code-review.html)
-
-## Issue 规范
-
-### Bug Report
-
-```markdown
-## Bug 描述
-
-简要描述遇到的问题。
-
-## 复现步骤
-
-1. 打开 xxx 页面
-2. 点击 xxx 按钮
-3. 输入 xxx 数据
-4. 看到错误
-
-## 期望行为
-
-描述你期望的正确行为。
-
-## 实际行为
-
-描述实际发生的行为。
-
-## 环境信息
-
- OS: Windows 11
- PHP: 8.2
- ThinkPHP: 6.1.x
- Node.js: 22.x
- Browser: Chrome 120
-```
-
-### Feature Request
-
-```markdown
-## 功能描述
-
-简要描述你希望添加的功能。
-
-## 使用场景
-
-描述这个功能的使用场景和价值。
-
-## 方案建议
-
-如果有实现思路，请描述。
-```
-
-## 代码风格
-
- PHP：遵循 PSR-12 规范
- TypeScript/Vue：遵循 ESLint + Prettier 配置
- 详见 [前端编码规范](/zh/standards/frontend-code.html) 和 [后端编码规范](/zh/standards/backend-code.html)
+- 页标题编号与侧边栏一致；跨章链接用绝对路径 + `.html`
+- 代码示例首行注释标注源文件路径
+- 示例代码须与当前代码行为一致（过期示例比没有更糟）

 ## 行为准则

- 尊重每一位贡献者
- 建设性地提出意见和建议
- 专注于对社区有益的事情
- 不接受任何形式的骚扰
+对事不对人；技术分歧以可验证的事实收敛；帮助新手理解而非劝退。

-## 总结
+## 相关

-贡献指南涵盖开发环境搭建、分支策略、Commit 规范、PR 流程、Issue 模板、代码风格等内容。核心原则：遵循规范、充分测试、清晰描述、尊重他人。
+- [12.7 代码审查清单](/zh/standards/code-review.html)
+- [11.11 CI/CD 与质量门禁](/zh/deploy/ci-cd.html)