贡献指南

GraphFrames 项目欢迎新的贡献者。本指南提供了一份端到端的清单——从准备工作站到提交拉取请求——以便您能够自信地进行迭代并保持测试套件通过。

1. 前提条件

在克隆仓库之前，请确保已安装以下工具：

1.1 安装所需工具

macOS (Homebrew)

brew update
brew install git openjdk@17 python@3.12 pipx protobuf bufbuild/buf/buf
pipx install poetry

将 Java 工具链添加到您的 shell 配置文件中（例如 ~/.zshrc 或 ~/.bashrc）：

export JAVA_HOME="$(/usr/libexec/java_home -v17)"
export PATH="$JAVA_HOME/bin:$PATH"

Ubuntu / Debian

sudo apt update
sudo apt install -y git openjdk-17-jdk python3 python3-venv python3-pip curl protobuf-compiler
python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install poetry
curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64.tar.gz" \
  | sudo tar -xzf - -C /usr/local --strip-components=1

将 Java 工具链添加到您的 shell 配置文件中（例如 ~/.zshrc 或 ~/.bashrc）：

export JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64"
export PATH="$JAVA_HOME/bin:$PATH"

可选：独立 Apache Spark 发行版

poetry install（稍后详述）已自动引入匹配版本的 PySpark 和 Spark Connect。若您还需要独立的 Spark shell 或 spark-submit，请下载与构建版本 spark.version（当前为 3.5.6）匹配的发行版，并通过 SPARK_HOME 环境变量配置路径：

curl -O https://downloads.apache.org/spark/spark-3.5.6/spark-3.5.6-bin-hadoop3.tgz
mkdir -p "$HOME/.local/spark"
tar -xzf spark-3.5.6-bin-hadoop3.tgz -C "$HOME/.local/spark"
export SPARK_HOME="$HOME/.local/spark/spark-3.5.6-bin-hadoop3"
export PATH="$SPARK_HOME/bin:$PATH"

提示：要构建针对 Spark 4.x 的版本，请将 -Dspark.version= 传递给 ./build/sbt 或传递给 Python 工作流中引用的 jar 构建辅助脚本。

2. 克隆仓库

1. 在 GitHub 上复刻仓库（推荐）并复制克隆 URL。
2. Clone your fork and switch into the workspace:

   git clone https://github.com/<your-user>/graphframes.git
   cd graphframes

3. Configure the upstream remote to stay in sync:

   git remote add upstream https://github.com/graphframes/graphframes.git
   git fetch upstream

4. Create a topic branch for your change:

   git checkout -b feature/my-change

3. Scala / JVM 工作流程

GraphFrames 在 ./build/sbt 提供了一个已检入的 sbt 启动器；不需要单独安装 sbt。

3.1 编译项目

./build/sbt compile

首次运行会下载所有依赖项，可能需要几分钟时间。如果编译因-Xfatal-warnings报错提示弃用的java.net.URL构造函数而失败，请确保构建使用的是您的Java 17工具链。您可以通过以下方式强制使用：

./build/sbt -java-home "$JAVA_HOME" compile

3.2 格式化 Scala 代码

您可以使用项目的预提交钩子一次性自动格式化所有Scala代码。

3.3 运行 Scala 测试

运行完整的测试套件：

./build/sbt test

在迭代过程中专注于特定套件：

./build/sbt "core/testOnly org.graphframes.lib.PageRankSuite"

3.4 有用的 sbt 任务

4. Python 工作流程

Python 包位于 python/ 目录下，并使用 Poetry 进行依赖管理。

要构建 GraphFrames 程序集 jar 并运行 Python 测试套件，您可以直接使用提供的辅助脚本和 pytest。

1. 安装 Python 依赖项（从 python/ 目录）：

   poetry install --with dev,tutorials,docs

2. 构建适用于您 Spark 版本的所需 GraphFrames JAR：

   poetry run python ./dev/build_jar.py

   此脚本将自动为 Spark 3.5.x（或指定的 4.x 版本）构建正确的 JAR。您无需直接运行 sbt。

3. 运行 Python 测试套件：

   poetry run pytest -vvv

   测试配置将自动选择正确的JAR包和Spark版本（详见python/tests/conftest.py）。

   通过导出 SPARK_CONNECT_MODE_ENABLED=1 启用 Spark Connect 覆盖：

   SPARK_CONNECT_MODE_ENABLED=1 poetry run pytest -vvv

4. 可选地强制执行格式化和代码检查：

   poetry run black graphframes tests
   poetry run isort graphframes tests
   poetry run flake8 graphframes tests

您可以在CI配置中查看此工作流程的实际运行情况。

4.1 PySpark 冒烟测试

构建完程序集jar包后，您可以在交互式PySpark会话中验证您的构建。

1. Export the assembly path from the repository root:

   export GRAPHFRAMES_ASSEMBLY=$(ls ../core/target/scala-${SCALA_VERSION%.*}/graphframes-assembly*.jar | tail -n 1)

   如果命令未找到jar文件，请重新运行./build/sbt core/assembly并确认 SCALA_VERSION与target/下的目录匹配（例如2.12.20）。

2. Launch PySpark from the Poetry environment so the graphframes package is on the Python path:

   cd python
   poetry run pyspark \
    --driver-memory 2g \
    --jars "$GRAPHFRAMES_ASSEMBLY" \
    --conf spark.driver.extraClassPath="$GRAPHFRAMES_ASSEMBLY" \
    --conf spark.executor.extraClassPath="$GRAPHFRAMES_ASSEMBLY"

3. In the shell, run a simple PageRank example:

   from graphframes import GraphFrame
   from pyspark.sql import SparkSession
   
   spark = SparkSession.builder.getOrCreate()
   
   v = spark.createDataFrame([(1,), (2,), (3,)], ["id"])
   e = spark.createDataFrame([(1, 2), (2, 3), (3, 1)], ["src", "dst"])
   
   g = GraphFrame(v, e)
   g.pageRank(resetProbability=0.15, tol=0.01).vertices.show()

   完成操作后，使用 spark.stop() 或 Ctrl+D 退出 shell。

4. Return to the repository root:

   cd ..

4.2 PySpark Connect 更新

PySpark Connect 插件消息位于 connect/src/main/protobuf。在对消息进行任何更改后，例如添加新 API 后，需要执行以下操作：

• 重新编译连接项目以触发生成新的Java类：./build/sbt connect/compile
• 通过 buf 从 protobuf 重新生成 Python 类：buf generate

5. 预提交钩子

启用捆绑的 pre-commit 钩子，以便在推送分支前捕获格式化和代码检查问题：

pipx install pre-commit  # or: pip install pre-commit
pre-commit install
pre-commit run --all-files

6. 制作和测试更改

1. 编辑相关文件。
2. 重新运行与您的更改相关的 Scala 和/或 Python 工作流。
3. Check your working tree:

   git status

4. Stage and commit with a descriptive message:

   git add <files>
   git commit -m "feat: describe your change"

5. Push your branch and open a pull request:

   git push origin feature/my-change

6. Keep your branch current by rebasing on the latest upstream changes:

   git fetch upstream
   git rebase upstream/master

7. 更新文档

GraphFrames 文档使用 Typelevel Laika 构建。Markdown 格式的文档文件位于 docs/src 中。

7.1 Laika 指令

以下自定义 Laika 指令是在内置指令基础上提供的：

• @pydoc(类名)，例如，@pydoc(graphframes.GraphFrame) -- 引用该类的 PySpark API 文档
• @scaladoc(class-name)，例如 @scaladoc(org.graphframes.GraphFrame) —— 引用该类的 Scala API 文档
• @srcLink(sub-path)，例如 @srcLink(python/graphframes/tutorials/stackexchange.py) -- 链接到github上的源代码

以下内置的 Laika 指令可能很有用。

• @image

一个示例是：

@:image(/img/graphframes-internals/graphframes-overview.png) {
    intrinsicWidth = 600
    alt = "An overview of GraphFrames and Apache Spark connection"
    title = "GraphFrames Overview"
}

内置指令的完整列表可在 Laika 文档 中找到。

7.2 构建与预览

要构建文档并运行预览服务器，请执行 ./build/sbt docs/laikaPreview。

8. 快速参考

您现在已准备好开始使用 GraphFrames 进行迭代开发。每当设置新机器或更新本地开发工作流程时，请重新参考本指南。