贡献给 SkyPilot#

感谢您对贡献 SkyPilot 的兴趣！我们欢迎并珍视对项目的所有贡献，包括但不限于

  • Bug 报告 和 讨论

  • 用于 bug 修复和新功能的 Pull 请求

  • 使代码库更健壮的测试用例

  • 示例

  • 文档

  • SkyPilot 的教程、博客文章和演讲

贡献代码#

我们使用 GitHub 来跟踪问题和功能。对于新贡献者，我们推荐查看标记为 “good first issue”（适合新手的问题） 的议题。

安装用于开发的 SkyPilot#

按照以下步骤设置用于贡献 SkyPilot 的本地开发环境。

创建 conda 环境#

为避免包冲突，请创建并激活一个干净的 conda 环境

# SkyPilot requires 3.7 <= python <= 3.11.
conda create -y -n sky python=3.10
conda activate sky

安装 SkyPilot#

要安装 SkyPilot，请将 skypilot-org/skypilot fork 到您的 GitHub 账户并运行

# Clone your forked repo
git clone https://github.com/<your-github-username>/skypilot.git

# Set upstream to keep in sync with the official repo
cd skypilot
git remote add upstream https://github.com/skypilot-org/skypilot.git

# Install SkyPilot in editable mode
pip install -e ".[all]"
# Alternatively, install specific cloud support only:
# pip install -e ".[aws,azure,gcp,lambda]"

# Install development dependencies
pip install -r requirements-dev.txt

(可选) 安装 pre-commit#

您还可以安装 pre-commit 钩子，以帮助在提交时自动格式化您的代码

pip install pre-commit
pre-commit install

测试#

要运行冒烟测试（注意：运行所有冒烟测试将启动约 20 个集群）

# Run all tests on AWS and Azure (default smoke test clouds)
pytest tests/test_smoke.py

# Terminate a test's cluster even if the test failed (default is to keep it around for debugging)
pytest tests/test_smoke.py --terminate-on-failure

# Re-run last failed tests
pytest --lf

# Run one of the smoke tests
pytest tests/test_smoke.py::test_minimal

# Only run managed spot tests
pytest tests/test_smoke.py --managed-spot

# Only run test for GCP + generic tests
pytest tests/test_smoke.py --gcp

# Change cloud for generic tests to Azure
pytest tests/test_smoke.py --generic-cloud azure

用于代码性能分析，请使用

pip install py-spy # py-spy is a sampling profiler for Python programs
py-spy record -t -o sky.svg -- python -m sky.cli status # Or some other command
py-spy top -- python -m sky.cli status # Get a live top view
py-spy -h # For more options

在容器中测试#

在从头搭建的干净环境中测试您的更改通常很有用。使用容器是实现此目的的好方法。我们有一个名为 berkeleyskypilot/skypilot-debug 的开发容器镜像，我们用它在容器内部调试 skypilot。通过运行以下命令使用此镜像

docker run -it --rm --name skypilot-debug berkeleyskypilot/skypilot-debug /bin/bash
# On Apple silicon Macs:
docker run --platform linux/amd64 -it --rm --name skypilot-debug berkeleyskypilot/skypilot-debug /bin/bash

它具有一些您可能会觉得有用的便捷功能（参见 Dockerfile）

  • 常用依赖和一些实用工具（rsync, screen, vim, nano 等）已预安装

  • requirements-dev.txt 已预安装

  • 开发/调试相关的环境变量已正确设置

  • 容器启动时，自动将最新的 master 分支克隆到 /sky_repo/skypilot。

    • 请注意，您仍然需要手动运行 pip install -e ".[all]" 来安装 skypilot，它不是预安装的。

    • 如果您的分支在 SkyPilot 仓库中，您可以运行 git checkout <your_branch> 切换到您的分支。

提交 Pull 请求#

  • Fork SkyPilot 仓库并为您的更改创建一个新分支。

  • 如果相关，请为您的更改添加测试。对于涉及核心系统的更改，请运行 冒烟测试 并确保它们通过。

  • 遵循 Google 编码风格指南。

  • 通过运行 format.sh 确保代码格式正确。

    • [可选] 您还可以通过运行 pre-commit install 安装 pre-commit 钩子，以在提交时自动格式化您的代码。

  • 将您的更改推送到您的 fork，并在 SkyPilot 仓库中打开一个 pull 请求。

  • 在 PR 描述中，添加一个 Tested: 部分来描述执行的相关测试。

一些通用的工程实践建议#

这些是建议，不是必须遵循的严格规则。如有疑问，请遵循 编码风格指南。

  • 使用 TODO(作者姓名)/FIXME(作者姓名) 而不是空白的 TODO/FIXME。这对于追踪问题至关重要。如果是别人的问题，您可以用您的名字写 TODO 并将其分配给其他人（在 github 上）。

  • 合并分支后删除您的分支。这可以保持仓库干净并加快同步速度。

  • 如果这是错误，请使用异常。只在调试或验证目的时使用 assert。这是因为异常消息通常包含更多信息。

  • 对于满足以下标准的第三方模块，请使用 LazyImport

    • 该模块在 import sky 期间被导入

    • 该模块有显著的导入时间（例如 > 100ms）

  • 衡量导入时间

    • 基本检查：python -X importtime -c "import sky"

    • 详细可视化：使用 tuna 分析导入时间

      python -X importtime -c "import sky" 2> import.log
tuna import.log

  • 使用现代 Python 特性和风格，提高代码质量。

    • 对于短表达式，使用 f-string 而不是 .format() 以提高可读性。

    • 使用 class MyClass: 而不是 class MyClass(object):。后者是针对 python2.x 的一种变通方法。

    • 使用 abc 模块定义抽象类，以确保所有抽象方法都得到实现。

    • 使用 Python 类型提示。但不应仅仅为了类型提示而导入外部对象。相反，应在 if typing.TYPE_CHECKING: 下导入仅用于类型提示的外部对象。

开发人员环境变量#

  • 设置 export SKYPILOT_DISABLE_USAGE_COLLECTION=1 可禁用使用情况日志记录。

  • 设置 export SKYPILOT_DEBUG=1 可显示调试日志（使用 logging.DEBUG 级别）。

  • 设置 export SKYPILOT_MINIMIZE_LOGGING=1 可最小化日志输出。当试图避免多行输出（例如演示时）时很有用。