向 gsutil 贡献代码

概览

我们很愿意接受用户编写的 gsutil 代码更改。以下是一些准则:

  1. 在接受用户提交的代码之前,我们必须克服几个法律障碍。请填写个人或企业贡献者许可协议:

    请按照上述两个链接之一访问相应的 CLA 和说明,了解如何签署和返回 CLA。收到您的 CLA 后,我们会将您添加到官方贡献者列表中,并且能够接受您的补丁程序。

  2. 如果您发现了错误或对某项功能有任何改进想法,我们建议您查看 https://github.com/GoogleCloudPlatform/gsutil/issues,了解是否已有其他用户报告过相同的情况。您还可以在此处订阅该问题的更新。

  3. 如果 GitHub 问题尚不存在,请在发送实际代码之前先针对您的想法创建一个问题。通常情况下,我们可以针对您的想法展开讨论,并提出一些可方便您日后的修订工作的建议。

  4. 我们不会仅为了一小部分用户而添加命令行选项,尤其是在有其他方法可以满足此类需求的情况下。添加此类选项会使代码复杂化,并且还会使需要阅读选项文档的“字母汤”列表的用户增加开销。

  5. 虽然 gsutil 的很多特性都是特定于 Cloud Storage 的,但它也适用于其他云存储服务商。对于专门针对其他服务商进行的 gsutil 支持特性更改,只要这些更改不会使 gsutil 对 Cloud Storage 的运行效果变差,我们就会很愿意接受这些更改。 如果您进行此类更改,我们建议将了解该特定服务商的人员添加为代码审核者(见下文)。

  6. 您可以从 GitHub 代码库中签出 gsutil 代码:

    https://github.com/GoogleCloudPlatform/gsutil
    

    如需克隆该代码库的只读副本,请使用以下命令:

    git clone git://github.com/GoogleCloudPlatform/gsutil.git
    

    如需将您自己的更改推送到 GitHub,请点击代码库页面上的“创建分支”(Fork) 按钮,然后从您自己的分支克隆代码库。

  7. gsutil Git 代码库使用 Git 子模块拉取外部模块。 签出代码库后,请务必进入 gsutil 顶级目录并运行以下命令来同时拉取子模块:

    git submodule update --init --recursive
    
  8. 请务必针对修改后的代码运行所有测试。为此,请将目录更改为 gsutil 顶级目录并运行以下命令:

    ./gsutil test
    

    上述测试需要很长时间才能运行,因为它们会将许多请求发送到生产服务。gsutil test 命令具有一个 -u 参数,表示仅运行单元测试。这些测试会快速运行,因为它们通过内存中的模拟存储服务实现来执行。如需仅运行单元测试,请运行以下命令:

    ./gsutil test -u
    

    如果您对 boto 进行了更改,请运行 boto 测试。对于这些测试,您需要使用 HMAC 凭据(来自 gsutil config -a),因为当前的 boto 测试套件不会导入 OAuth2 处理程序。您还需要安装一些 python 模块。将目录更改为 boto 根目录 third_party/boto,然后运行以下命令:

    pip install -r requirements.txt
    

    (您可能需要使用 sudo 运行此命令。)确保各个安装都成功完成。否则,您可能需要再次运行安装命令。

    然后,确保 .boto 文件定义了 HMAC 凭据(boto 测试不会加载 OAUTH2 插件),以及将目录更改为 boto 的测试目录并运行以下命令:

    python test.py unit
    python test.py -t s3 -t gs -t ssl
    
  9. 请考虑为您的更改贡献测试代码,尤其在此更改会影响任何核心 gsutil 代码(例如 gsutil cp 命令)的情况下。

  10. 请使用 GitHub 代码库根目录中的配置文件运行 yapf linter。

    yapf -irp .

  11. 向我们发送代码时,请将 PR 提交到 gsutil GitHub 代码库。如需有关创建 GitHub PR 方面的帮助,请参阅此 GitHub 帮助文档