Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
160 lines (89 loc) · 5.48 KB

CONTRIBUTING.md

File metadata and controls

160 lines (89 loc) · 5.48 KB

qKnow 开源项目 Pull Request (PR) 规范

本文档旨在规范项目的 Pull Request (PR) 提交与评审流程，提升协作效率，保证代码质量，降低维护成本。所有参与项目开发的贡献者均需遵守本规范。

一、PR 提交前提

  1. 确保提交的代码符合项目的编码规范（如命名规范、代码格式、注释规范等）。

  2. 本地已完成充分测试，包括但不限于单元测试、功能测试，确保新增或修改的代码无新增 Bug，且不影响现有功能正常运行。

  3. 已同步上游（上游主仓库）最新代码，解决本地分支与目标分支的冲突。

  4. 确认提交的功能或修复的问题符合项目规划或 Issue 描述，未超出范围。若涉及重大功能变更，需提前在项目 Issue 或讨论区与核心维护者达成共识。

  5. 关于授权，请阅读我们的许可与贡献者协议 。

二、分支规范

2.1 分支命名规则

分支命名需清晰、规范，格式为：类型/简短描述，其中类型包括：

  • feature：新增功能

  • fix：修复 Bug

  • docs：文档更新

  • style：代码格式调整（不涉及代码逻辑）

  • refactor：代码重构（不新增功能、不修复 Bug）

  • test：补充或修改测试代码

示例：

  • feature/kg-structured-extraction（新增图谱结构化抽取功能）

  • fix/kg-unstructured-parse（修复图谱非结构化文本解析异常）

  • docs/update-readme（更新 README 文档）

2.2 目标分支选择

  • 优先合并到develop 分支。

三、Commit 信息规范

PR 由多个 Commit 组成，每个 Commit 的信息需准确、简洁，遵循以下格式：


<type>(<scope>): <subject>

[body]

[footer]

3.1 各部分说明

  • type：提交类型，与分支命名的类型一致（feature、fix、docs、style 等）。

  • scope：可选，指定提交影响的范围（如模块、功能、文件等），示例：feature(login)、fix(graph)。

  • subject：提交的简短描述，不超过 50 字符，首字母小写，结尾不加句号。

  • body：可选，详细描述提交的内容、修改原因、解决的问题等，换行时注意空行分隔。

3.2 示例


feature(kg): 新增图谱结构化抽取功能

新增结构化抽取接口（/kg/structured/extract）
实现实体、关系、属性的自动抽取与图谱映射逻辑
优化抽取结果去重策略，提升图谱数据准确性


fix(kg): 修复图谱非结构化文本抽取失败问题

原因：非结构化文本（PDF/Word）解析时，特殊字符导致实体边界识别错误，进而引发抽取中断。
解决方案：优化文本预处理逻辑，添加特殊字符过滤与分词校正，完善异常捕获机制。

四、PR 描述规范

提交 PR 时，需在 Gitee PR 编辑页面填写清晰、详细的描述，帮助评审者快速了解 PR 内容。建议使用以下模板：


## 1. PR 目的
- 描述本次 PR 的核心目的（新增功能/修复 Bug/文档更新等）
- 关联 Issue：#xxx（必填，若无 Issue 可说明）

## 2. 实现内容
- 列出主要的修改点、实现的功能模块、修复的具体问题
- 可附加核心逻辑说明、设计思路等

## 3. 测试情况
- 本地测试：列出已完成的测试用例（单元测试、功能测试等）
- 测试环境：是否在测试环境验证，结果如何
- 待测试点（若有）：需要评审者重点测试的内容

## 4. 其他说明
- 是否涉及不兼容变更：是/否，若为是请详细说明
- 是否需要文档同步更新：是/否
- 其他需要评审者注意的事项（如依赖变更、性能影响等）

## 5. 截图/录屏（可选）
- 若涉及 UI 变更、功能演示，可附加截图或录屏链接

4.1 注意事项

  • PR 描述需使用中文，语言简洁、准确，避免歧义。

  • 必须关联相关的 Issue（若存在），便于追溯需求和问题。

  • 对于复杂的 PR，建议分点详细说明，降低评审难度。

五、PR 提交流程

  1. 在 Gitee 上 Fork 项目到个人仓库（首次贡献时）。

  2. 克隆个人仓库到本地：git clone https://gitee.com/your-username/qKnow。

  3. 创建并切换到符合规范的分支：git checkout -b feature/xxx。

  4. 完成代码开发和测试，提交 Commit（遵循 Commit 信息规范）。

  5. 推送本地分支到个人仓库：git push origin feature/xxx。

  6. 登录 Gitee，进入个人仓库，点击「Pull Request」→「新建 Pull Request」。

  7. 选择目标分支（上游仓库的对应分支）和源分支（个人仓库的开发分支）。

  8. 填写 PR 描述（遵循 PR 描述规范），检查信息无误后提交。

六、PR 拒绝/关闭规范

  • 若 PR 不符合规范（如分支错误、描述不完整、代码质量不达标），评审者可拒绝并说明具体原因，要求贡献者整改后重新提交。

  • 若 PR 涉及的功能与项目规划不符、存在重大设计问题且无法协商解决，核心维护者可关闭 PR，并在评论区详细说明原因，感谢贡献者的付出。

  • 贡献者可自行关闭未合并的 PR（如发现提交错误、功能无需实现等），关闭时建议说明原因。

七、附则

  • 本规范自发布之日起生效。

  • 贡献者在 PR 提交和评审过程中需遵循开源协作礼仪，尊重评审意见，友好沟通。

qKnow项目维护团队 更新日期：2026-03-27