如何贡献

感谢您对GraphScope项目的关注。

GraphScope 是一个专注于大规模图计算的开源项目，拥有一个乐于帮助新贡献者的友好开发者社区。我们欢迎各种类型的贡献，从代码改进到文档编写。

行为准则

在参与贡献或与我们的社区互动之前，请阅读我们的行为准则。

社区

参与GraphScope项目的一个良好开端是加入我们的讨论，并通过不同的沟通渠道与我们互动。 以下是几种与我们联系的方式：

GitHub 讨论

我们使用GitHub Discussion来提问和解答问题。欢迎提出您对GraphScope的任何疑问或在使用过程中遇到的代码问题。

Slack

加入Slack频道参与讨论。

报告错误

如果您在GraphScope中发现错误，请先测试最新版本的GraphScope以确保您的问题尚未被修复。如果没有，请在GitHub上搜索我们的问题列表，查看是否已有类似问题被提出。

如果您确认该错误尚未被报告提交错误问题，请在编写任何代码之前进行操作。提交问题时，请包含清晰简洁的问题描述、相关代码或错误信息以及重现问题的步骤。

请求功能

如果您发现GraphScope缺少您需要的功能，请在GitHub上提交功能请求issue，描述该功能、其必要性以及预期工作方式。其他用户可能也有类似需求，事实上GraphScope的许多功能都是基于用户需求而添加的。

改进文档

为项目做出贡献的一个好方法是改进文档。如果您发现任何不完整或不准确的文档，请与社区分享您的知识。

文档改进也是熟悉我们的提交和审核流程（下文将讨论）的绝佳方式，无需进行大量本地开发环境设置。 事实上，许多仅涉及文档的修改可以直接在GraphScope文档页面中通过点击"Edit On GitHub"按钮完成。系统将自动为您处理创建分支和拉取请求的操作。

TBF: 添加如何帮助文档的链接 TBF: 添加如何构建文档的链接

贡献代码与文档变更

如果您希望为GraphScope贡献新功能或修复错误，请先在GitHub issue上讨论您的想法。 如果尚无相关issue，请创建一个。可能已有人在处理该问题，或者其中存在某些特定复杂性， 在开始编码前您应当了解清楚。通常有多种方法可以解决问题，因此在花费时间提交可能无法合并的PR之前， 找到正确的方法非常重要。

安装pre-commit

GraphScope 使用 pre-commit 来确保不会意外将敏感信息提交到 Git 仓库。在贡献代码前，请通过以下命令安装 pre-commit：

$ pip3 install pre-commit

使用以下命令配置必要的预提交钩子：

$ pre-commit install  --install-hooks

小修复

对于仅影响文档的小改动，您无需创建GitHub工单。如果符合以下准则，只需在PR标题前添加前缀"[MINOR]"：

  • 语法、用法和拼写修正，影响不超过2个文件

  • 文档更新涉及不超过2个文件且不超过500字。

Fork 并创建分支

Fork主GraphScope代码库并克隆到本地机器。如需帮助，请参阅GitHub帮助页面。

创建一个具有描述性名称的分支。

一个好的分支名称应该是（假设您正在处理的是工单 #42）：

$ git checkout -b 42-add-chinese-translations

运行测试套件

查看我们的测试操作指南以获取帮助。

实现您的修复或功能

现在，您已准备好进行更改。随时寻求帮助，因为每个人最初都是新手！

正确获取代码格式与样式

您的补丁应遵循与项目其他部分相同的规范并通过相同的代码质量检查。 请遵循我们的代码风格指南以获得正确的代码格式和样式。

提交您的更改

要提交您的更改，您需要向主仓库发起一个拉取请求（PR）。如果您是GitHub的新手，可以在GitHub的文档中找到相关操作指南。GraphScope要求PR标题遵循特定格式（也称为Conventional Commits规范），具体格式取决于您所做的更改类型。格式如下：

类型(范围): 关于PR的简要描述

以下是一些有效的PR标题示例：

  • 修复：修正拼写错误

  • 功能(交互式): 支持 g.V().outE().inV()

  • 重构!: 停止支持 Python 3.8

  • 功能(分析): 为PageRank添加delta版本

注意

请注意，由于拉取请求标题只有一行，您必须使用 ! 来表示重大变更。

type 必须是以下选项之一：

  • 构建：影响构建系统或外部依赖项的更改（示例范围：gulp、broccoli、npm）

  • ci: 对我们的CI配置文件和脚本的更改

  • docs: 仅文档变更

  • 功能: 新增特性

  • 修复: 一个错误修复

  • perf: 提升性能的代码变更

  • 重构：既不修复错误也不添加功能的代码变更

  • 测试：添加缺失的测试或修正现有测试

  • chore: 开发中的常规任务

scope 是可选的。但如果指定了，则必须是以下之一：

  • 核心

  • python

  • k8s

  • 协调器

  • 一

  • 交互式

  • 洞察

  • 分析

  • 学习

除了常规的提交规范外，我们还要求带有功能更新的PR（即标题以feat:开头）必须更新相应的文档。该仓库部署了CI检查来确保这一点。

讨论并保持您的拉取请求更新

你很可能会收到关于拉取请求的反馈或修改要求。这是提交过程中的重要环节，对于正确评估你的变更是必要的，所以不要气馁！

如果维护者要求你"rebase"你的拉取请求，这意味着代码发生了大量变更，你需要更新你的分支以便更容易合并。要了解更多关于Git中rebase的信息，请参考推荐的工作流程：

$ git checkout 42-add-chinese-translations
$ git pull --rebase upstream main
$ git push --force-with-lease 42-add-chinese-translations

如果正在等待回复，欢迎在拉取请求中留言提醒审阅者。 遇到不熟悉的词汇或缩写时，可查阅此术语表。

合并PR（仅限维护者）

只有维护者在满足以下条件时才能将拉取请求合并到主分支：

  • 它已通过CI测试。

  • 至少需要两位维护者批准。如果PR由维护者发起，则仅需额外一位批准即可。

  • 没有请求的更改。

  • 它与当前的主分支保持同步。

发布版本（仅限维护者）

待办事项(dongze): 待定

如何审查拉取请求

我们欢迎社区的贡献，并鼓励大家审阅拉取请求。在审阅拉取请求时，请考虑以下事项：

  • 代码是否遵循我们的[行为准则][1]？

  • 代码是否解决了问题或功能需求中描述的问题？

  • 是否存在需要考虑的潜在副作用或边缘情况？

  • 是否包含测试以确保代码按预期工作？

如果您对拉取请求有任何疑问或顾虑，请在拉取请求上留言或直接联系贡献者。

持续集成测试

所有包含代码变更的拉取请求都必须通过GitHub Actions的持续集成(CI)测试

该拉取请求的变更将触发一次CI测试运行。理想情况下，代码变更会在GraphScope支持的所有平台配置上通过测试（"显示绿色"）。这意味着所有测试都通过且没有代码规范错误。然而在现实中，CI基础设施本身在特定平台上失败（"显示红色"）的情况并不罕见。关键是要仔细检查所有失败（"红色"）测试的结果，以确定失败是否由拉取请求中的变更引起。