贡献 — Python 文档

来自菜鸟教程
Celery/docs/latest/contributing
跳转至：导航、​搜索

贡献

欢迎！

这份文件相当广泛，你真的不需要为了小的贡献而详细研究它；

最重要的规则是贡献必须是简单的，社区是友好的，而不是在细节上挑剔，比如编码风格。


如果您正在报告错误，您应该阅读下面的报告错误部分，以确保您的错误报告包含足够的信息来成功诊断问题，如果您正在贡献代码，您应该尝试模仿您在代码周围看到的约定正在努力，但最终所有补丁都会由合并更改的人清理，所以不要太担心。

社区行为准则

我们的目标是维持一个对每个人都感到愉快的多元化社区。 因此，如果每个为社区做出贡献并与社区互动的人都遵守本行为准则，我们将不胜感激。

该行为准则涵盖了我们作为社区成员在任何论坛、邮件列表、维基、网站、互联网中继聊天 (IRC)、公开会议或私人信件中的行为。

该行为准则主要基于 Ubuntu 行为准则 和 Pylons 行为准则 。

体贴

你的工作会被别人使用，而你又会依赖别人的工作。 您做出的任何决定都会影响用户和同事，我们希望您在做出决定时考虑这些后果。 即使当时不明显，我们对 Celery 的贡献也会影响其他人的工作。 例如，在发布期间对代码、基础设施、政策、文档和翻译的更改可能会对他人的工作产生负面影响。


尊重他人

Celery 社区及其成员相互尊重。 每个人都可以为 Celery 做出宝贵的贡献。 我们可能并不总是同意，但分歧不是行为不端和举止不当的借口。 我们可能都会时不时地经历一些挫折，但我们不能让这种挫折变成人身攻击。 重要的是要记住，一个人们感到不舒服或受到威胁的社区并不是一个富有成效的社区。 我们希望 Celery 社区的成员在与其他贡献者以及 Celery 项目之外的人和 Celery 用户打交道时要尊重他人。


合作

协作是 Celery 和更大的自由软件社区的核心。 我们应该始终对合作持开放态度。 你的工作应该透明地完成，并且来自 Celery 的补丁应该在制作完成后返还给社区，而不仅仅是在发行版发布时。 如果您希望为现有的上游项目编写新代码，请至少让这些项目了解您的想法和进展。 很多人不可能从上游，甚至从你的同事那里就一个想法的正确实施达成共识，所以在你开始之前不要觉得有必要达成一致，但至少要让外界了解你的工作，并以一种允许局外人测试、讨论和为您的工作做出贡献的方式发布您的工作。


当您不同意时，请咨询他人

政治和技术上的分歧一直在发生，Celery 社区也不例外。 重要的是，我们必须在社群和社群流程的帮助下，建设性地解决分歧和不同意见。 如果您真的想采用不同的方式，那么我们鼓励您制作衍生发行版或替代软件包，这些软件包仍然基于我们所做的工作，以尽可能利用核心的通用性。


当你不确定时，寻求帮助

没有人知道一切，也没有人被期望是完美的。 提出问题可以避免很多问题，因此鼓励提问。 那些被问到问题的人应该反应灵敏，乐于助人。 但是，在提出问题时，必须注意在适当的论坛中进行提问。


体谅下台

每个项目的开发人员来来去去，Celery 也不例外。 当您全部或部分离开或脱离项目时，我们要求您以尽量减少对项目中断的方式这样做。 这意味着您应该告诉人们您要离开并采取适当的步骤以确保其他人可以从您离开的地方接手。


报告错误

安全

您绝不能向错误跟踪器或其他公共场所报告与安全相关的问题、漏洞或错误，包括敏感信息。 相反，敏感的错误必须通过电子邮件发送到 security@celeryproject.org。

如果您想提交加密的信息，我们的 PGP 密钥是： 

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.15 (Darwin)

mQENBFJpWDkBCADFIc9/Fpgse4owLNvsTC7GYfnJL19XO0hnL99sPx+DPbfr+cSE
9wiU+Wp2TfUX7pCLEGrODiEP6ZCZbgtiPgId+JYvMxpP6GXbjiIlHRw1EQNH8RlX
cVxy3rQfVv8PGGiJuyBBjxzvETHW25htVAZ5TI1+CkxmuyyEYqgZN2fNd0wEU19D
+c10G1gSECbCQTCbacLSzdpngAt1Gkrc96r7wGHBBSvDaGDD2pFSkVuTLMbIRrVp
lnKOPMsUijiip2EMr2DvfuXiUIUvaqInTPNWkDynLoh69ib5xC19CSVLONjkKBsr
Pe+qAY29liBatatpXsydY7GIUzyBT3MzgMJlABEBAAG0MUNlbGVyeSBTZWN1cml0
eSBUZWFtIDxzZWN1cml0eUBjZWxlcnlwcm9qZWN0Lm9yZz6JATgEEwECACIFAlJp
WDkCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEOArFOUDCicIw1IH/26f
CViDC7/P13jr+srRdjAsWvQztia9HmTlY8cUnbmkR9w6b6j3F2ayw8VhkyFWgYEJ
wtPBv8mHKADiVSFARS+0yGsfCkia5wDSQuIv6XqRlIrXUyqJbmF4NUFTyCZYoh+C
ZiQpN9xGhFPr5QDlMx2izWg1rvWlG1jY2Es1v/xED3AeCOB1eUGvRe/uJHKjGv7J
rj0pFcptZX+WDF22AN235WYwgJM6TrNfSu8sv8vNAQOVnsKcgsqhuwomSGsOfMQj
LFzIn95MKBBU1G5wOs7JtwiV9jefGqJGBO2FAvOVbvPdK/saSnB+7K36dQcIHqms
5hU4Xj0RIJiod5idlRC5AQ0EUmlYOQEIAJs8OwHMkrdcvy9kk2HBVbdqhgAREMKy
gmphDp7prRL9FqSY/dKpCbG0u82zyJypdb7QiaQ5pfPzPpQcd2dIcohkkh7G3E+e
hS2L9AXHpwR26/PzMBXyr2iNnNc4vTksHvGVDxzFnRpka6vbI/hrrZmYNYh9EAiv
uhE54b3/XhXwFgHjZXb9i8hgJ3nsO0pRwvUAM1bRGMbvf8e9F+kqgV0yWYNnh6QL
4Vpl1+epqp2RKPHyNQftbQyrAHXT9kQF9pPlx013MKYaFTADscuAp4T3dy7xmiwS
crqMbZLzfrxfFOsNxTUGE5vmJCcm+mybAtRo4aV6ACohAO9NevMx8pUAEQEAAYkB
HwQYAQIACQUCUmlYOQIbDAAKCRDgKxTlAwonCNFbB/9esir/f7TufE+isNqErzR/
aZKZo2WzZR9c75kbqo6J6DYuUHe6xI0OZ2qZ60iABDEZAiNXGulysFLCiPdatQ8x
8zt3DF9BMkEck54ZvAjpNSern6zfZb1jPYWZq3TKxlTs/GuCgBAuV4i5vDTZ7xK/
aF+OFY5zN7ciZHkqLgMiTZ+RhqRcK6FhVBP/Y7d9NlBOcDBTxxE1ZO1ute6n7guJ
ciw4hfoRk8qNN19szZuq3UU64zpkM2sBsIFM9tGF2FADRxiOaOWZHmIyVZriPFqW
RUwjSjs7jBVNq0Vy4fCu/5+e+XLOUBOoqtM5W7ELt0t1w9tXebtPEetV86in8fU2
=0chn
-----END PGP PUBLIC KEY BLOCK-----

其他错误

错误总是可以在 邮件列表 中描述，但报告问题并确保及时响应的最佳方法是使用问题跟踪器。

  1. 创建一个GitHub账号。

您需要创建一个GitHub帐户才能创建新问题并参与讨论。

  1. 确定您的错误是否真的是错误。

如果您请求支持，则不应提交错误。 为此，您可以使用 邮件列表 或 IRC。 如果您仍然需要支持，您可以打开一个 github 问题，请在标题前加上 [QUESTION]。

  1. 确保您的错误尚未报告。

搜索相应的问题跟踪器。 如果发现了与您类似的错误，请检查您是否有可以报告的新信息以帮助开发人员修复错误。

  1. 检查您是否使用最新版本。

可以通过其他一些改进和修复来修复错误 - 它可能在错误跟踪器中没有现有报告。 确保您使用的是 celery、台球、kombu、amqp 和 vine 的最新版本。

  1. 收集bug信息。

为了获得修复错误的最佳机会，我们需要能够轻松重现导致错误的条件。 大多数情况下，此信息将来自 Python 回溯消息，但网站/文档/代码上的某些错误可能存在于设计、拼写或其他错误中。

  1. 如果错误来自 Python 回溯，请将其包含在错误报告中。

  2. 我们还需要知道您正在运行的平台（Windows、macOS、Linux 等）、您的 Python 解释器的版本、Celery 的版本以及您在错误发生时正在运行的相关包。

  3. 如果您要报告竞争条件或死锁，则回溯可能很难获得或可能没有那么有用。 尝试检查该过程以获取更多诊断数据。 一些想法：

    • 启用 Celery 的 断点信号 并使用它来检查进程的状态。 这将允许您打开 pdb 会话。

    • 使用 strace`_(Linux)、:command:`dtruss (macOS) 和 ktrace (BSD)、ltrace 和 收集跟踪数据lsof。

  4. 包括 celery report 命令的输出：

    $ celery -A proj report

    这也将包括您的配置设置，它会尝试删除已知敏感密钥的值，但请确保在提交之前验证信息，使其不包含 API 令牌和身份验证凭据等机密信息。

  5. 您的问题可能被标记为 需要测试用例 。 测试用例代表重现您的问题所报告的内容所需的所有详细信息。 测试用例可以是重现问题的一些最小代码，也可以是重现所述问题的详细说明和配置值。


  1. 提交bug。

默认情况下，GitHub 会通过电子邮件通知您何时对您的错误发表新评论。 如果您关闭了此功能，您应该不时回来查看以确保您不会错过试图修复错误的开发人员可能会提出的任何问题。


代码库的贡献者指南

内部详细信息有一个单独的部分，包括有关代码库和样式指南的详细信息。

阅读 代码贡献者指南 了解更多信息！


版本

版本号由主要版本、次要版本和版本号组成。 从 2.1.0 版开始，我们使用 SemVer 描述的版本语义：http://semver.org。

稳定版本在 PyPI 上发布，而开发版本仅在 GitHub git 存储库中作为标签提供。 所有版本标签都以“v”开头，因此版本 0.8.0 具有标签 v0.8.0。


分行

当前活动版本分支：

您可以通过查看 Changelog 来查看任何分支的状态：

如果分支处于活动开发状态，则最顶层的版本信息应包含元数据，例如： 

4.3.0
======
:release-date: TBA
:status: DEVELOPMENT
:branch: dev (git calls this master)

status 字段可以是以下之一：

  • PLANNING

    该分支机构目前处于试验阶段并处于规划阶段。

  • DEVELOPMENT

    分支正在积极开发中，但测试套件应该通过，产品应该可以工作并且可以供用户测试。

  • FROZEN

    分支被冻结，不再接受更多功能。 当一个分支被冻结时，重点是在发布之前尽可能多地测试版本。

开发分支

dev 分支（被 git 称为“master”）是开发下一个版本的地方。


维修分公司

维护分支以版本命名——例如，2.2.x 系列的维护分支命名为 2.2。

以前这些被命名为 releaseXX-maint。

我们目前维护的版本是：

  • 4.2

    这是当前的系列。

  • 4.1

    放弃对 python 2.6 的支持。 添加对 python 3.4、3.5 和 3.6 的支持。

  • 3.1

    官方支持 python 2.6、2.7 和 3.3，也支持 PyPy。


存档分支

存档分支仅用于保存历史记录，理论上，如果它们依赖于不再受官方支持的系列，则有人可以为这些分支提供补丁。

存档版本名为 X.Y-archived。

为了保持更清晰的历史记录并降低兼容性以继续改进项目，我们 目前没有任何存档版本 。


功能分支

主要的新功能在专门的分支中开发。 这些分支没有严格的命名要求。

功能分支在合并到发布分支后将被删除。


标签

  • 标签专门用于标记版本。 发布标签以 vX.Y.Z 格式命名，例如 v2.3.1。
  • 实验版本包含一个额外的标识符 vX.Y.Z-id – 例如 v3.0.0-rc1。
  • 正式发布后，实验标签可能会被移除。


处理功能和补丁

笔记

对 Celery 的贡献应该尽可能简单，所以这些步骤都不应被视为强制性的。

如果这是您首选的工作方法，您甚至可以通过电子邮件发送补丁。 我们不会再喜欢你了，你所做的任何贡献总是值得赞赏的！

但是，遵循这些步骤可能会使维护者的生活更轻松，并且可能意味着您的更改将更快被接受。


分叉和设置存储库

首先你需要 fork Celery 仓库； GitHub 指南中对此有一个很好的介绍： Fork a Repo。

克隆存储库后，您应该将副本检出到您机器上的目录： 

$ git clone git@github.com:username/celery.git

克隆存储库后，进入目录以设置对上游更改的轻松访问： 

$ cd celery
$ git remote add upstream git://github.com/celery/celery.git
$ git fetch upstream

如果您需要从上游引入新的更改，您应该始终使用 --rebase 选项到 git pull： 

git pull --rebase upstream master

使用此选项，您不会因合并提交注释而弄乱历史记录。 请参阅 在 git 中重新调整合并提交。 如果您想了解有关变基的更多信息，请参阅 GitHub 指南中的 Rebase 部分。

如果你需要在一个与 git 调用 master 不同的分支上工作，你可以像这样获取和检出远程分支： 

git checkout --track -b 5.0-devel upstream/5.0-devel

注意：任何功能或修复分支都应该从upstream/master创建。


使用 Docker 进行开发和测试

由于 Celery 的组件很多，例如代理和后端，因此可以利用 Docker 和 docker-compose 来大大简化开发和测试周期。 这里的 Docker 配置要求 Docker 版本至少为 17.13.0 和 docker-compose 1.13.0+。

Docker 组件可以在 docker/ 文件夹中找到，Docker 镜像可以通过以下方式构建： 

$ docker-compose build celery

并通过以下方式运行： 

$ docker-compose run --rm celery <command>

在哪里是在 Docker 容器中执行的命令。 –rm 标志表示容器在退出后应该被移除，这有助于防止不需要的容器堆积。

运行一些有用的命令：

  • bash

    像普通shell一样进入Docker容器

  • make test

    运行测试套件。 注意： 这将默认使用 python 3.8 运行测试。

  • tox

    运行 tox 并针对各种配置进行测试。 注意： 此命令将对 tox.ini 中定义的每个环境运行测试。 这需要一段时间。

  • pyenv exec python{3.6,3.7,3.8,3.9} -m pytest t/unit

    使用 pytest 运行单元测试。

    笔记： {3.6,3.7,3.8,3.9} means you can use any of those options. e.g. pyenv exec python3.7 -m pytest t/unit

  • pyenv exec python{3.6,3.7,3.8,3.9} -m pytest t/integration

    使用 pytest 运行集成测试

    笔记： {3.6,3.7,3.8,3.9} means you can use any of those options. e.g. pyenv exec python3.7 -m pytest t/unit

默认情况下，docker-compose 会在 Docker 容器中挂载 Celery 和 test 文件夹，允许代码更改和测试在 Docker 容器内立即可见。 docker/docker-compose.yml 文件中还定义了环境变量，例如要使用的代理和后端。

通过运行 docker-compose build celery，将创建一个名为 celery/celery:dev 的图像。 这个 docker 镜像已经安装了开发所需的所有依赖项。 pyenv用于安装多个python版本，docker镜像提供python 3.6、3.7、3.8和3.9。 默认 python 版本设置为 3.8。

docker-compose.yml 文件定义了运行集成测试所需的环境变量。 celery 服务还会挂载代码库并将 PYTHONPATH 环境变量设置为 /home/developer/celery。 通过设置 PYTHONPATH，该服务允许使用挂载的代码库作为全局模块进行开发。 如果您愿意，也可以运行 python -m pip install -e . 在开发模式下安装代码库。

如果您想运行 Django 或独立项目来手动测试或调试功能，您可以使用 docker-compose 构建的镜像并挂载您的自定义代码。 下面是一个例子：

假设一个文件夹结构，例如： 

+ celery_project
  + celery # repository cloned here.
  + my_project
    - manage.py
    + my_project
      - views.py
version: "3"

services:
    celery:
        image: celery/celery:dev
        environment:
            TEST_BROKER: amqp://rabbit:5672
            TEST_BACKEND: redis://redis
         volumes:
             - ../../celery:/home/developer/celery
             - ../my_project:/home/developer/my_project
         depends_on:
             - rabbit
             - redis
     rabbit:
         image: rabbitmq:latest
     redis:
         image: redis:latest

在前面的示例中，我们使用可以从该存储库构建的映像并安装 celery 代码库以及我们的自定义项目。


运行单元测试套件

如果您喜欢使用虚拟环境或仅在 docker 之外进行开发，则必须确保安装了所有必要的依赖项。 有多个需求文件可以更轻松地安装所有依赖项。 您不必使用每个需求文件，但必须使用 default.txt。 

# pip install -U -r requirements/default.txt

要运行 Celery 测试套件，您需要安装 requirements/test.txt。 

$ pip install -U -r requirements/test.txt
$ pip install -U -r requirements/default.txt

安装所需的依赖项后，您现在可以通过调用执行测试套件 :pypi:`pytest ` ： 

$ pytest t/unit
$ pytest t/integration

pytest 的一些有用选项是：

  • -x

    在第一个失败的测试中停止运行测试。

  • -s

    不要捕获输出

  • -v

    使用详细输出运行。

如果您只想为单个测试文件运行测试，您可以这样做： 

$ pytest t/unit/worker/test_worker.py

计算测试覆盖率

要计算测试覆盖率，您必须首先安装 :pypi:`pytest-cov` 模块。

安装 :pypi:`pytest-cov` 模块： 

$ pip install -U pytest-cov
HTML 格式的代码覆盖率

  1. 运行 pytest 并启用 --cov-report=html 参数：

    $ pytest --cov=celery --cov-report=html

  2. 然后覆盖输出将位于 htmlcov/ 目录中：

    $ open htmlcov/index.html


XML 中的代码覆盖率（Cobertura 风格）
  1. 运行 pytest 并启用 --cov-report=xml 参数：
$ pytest --cov=celery --cov-report=xml
  1. 然后覆盖 XML 输出将位于 coverage.xml 文件中。


在所有支持的 Python 版本上运行测试

在发行版的顶层目录中有一个 :pypi:`tox` 配置文件。

要为所有受支持的 Python 版本运行测试，只需执行： 

$ tox

如果您只想测试特定的 Python 版本，请使用 tox -e 选项： 

$ tox -e 3.7

构建文档

要构建文档，您需要安装 requirements/docs.txt 和 requirements/default.txt 中列出的依赖项： 

$ pip install -U -r requirements/docs.txt
$ pip install -U -r requirements/default.txt

此外，要在没有警告的情况下进行构建，您需要安装以下软件包： 

$ apt-get install texlive texlive-latex-extra dvipng

安装这些依赖项后，您应该能够通过运行来构建文档： 

$ cd docs
$ rm -rf _build
$ make html

确保构建输出中没有错误或警告。 构建成功后，文档可在_build/html获得。


使用 Docker 构建文档

通过运行构建文档： 

$ docker-compose -f docker/docker-compose.yml up --build docs

该服务将在 :7000 处启动本地文档服务器。 服务器正在使用 sphinx-autobuild 并启用 --watch 选项，因此您可以实时编辑文档。 检查 docker/docker-compose.yml 中的附加选项和配置


验证您的贡献

要使用这些工具，您需要安装一些依赖项。 这些依赖关系可以在 requirements/pkgutils.txt 中找到。

安装依赖项： 

$ pip install -U -r requirements/pkgutils.txt

pyflakes & PEP-8

为了确保您的更改符合 PEP 8 并运行 pyflakes 执行： 

$ make flakecheck

要在此命令失败时不返回负退出代码，请改用 flakes 目标： 

$ make flakes

API参考

要确保所有模块在 API 参考中都有相应的部分，请执行： 

$ make apicheck

如果文件丢失，您可以通过复制现有参考文件来添加它们。

如果模块是内部的，它应该是位于 docs/internals/reference/ 中的内部参考的一部分。 如果模块是公共的，它应该位于docs/reference/。

例如，如果模块 celery.worker.awesome 缺少引用，并且该模块被视为公共 API 的一部分，请使用以下步骤：

使用现有文件作为模板： 

$ cd docs/reference/
$ cp celery.schedules.rst celery.worker.awesome.rst

使用您喜欢的编辑器编辑文件： 

$ vim celery.worker.awesome.rst

    # change every occurrence of ``celery.schedules`` to
    # ``celery.worker.awesome``

使用您喜欢的编辑器编辑索引： 

$ vim index.rst

    # Add ``celery.worker.awesome`` to the index.

提交您的更改： 

# Add the file to git
$ git add celery.worker.awesome.rst
$ git add index.rst
$ git commit celery.worker.awesome.rst index.rst \
    -m "Adds reference for celery.worker.awesome"

伊索

Isort 是一个 Python 实用程序，用于帮助按字母顺序对导入进行排序并分成多个部分。 Celery 项目使用 isor 来更好地维护每个模块的导入。 如果有任何新模块或必须修改现有模块上的导入，请运行 isort。 

$ isort my_module.py # Run isort for one file
$ isort -rc . # Run it recursively
$ isort m_module.py --diff # Do a dry-run to see the proposed changes

创建拉取请求

当您的功能/错误修复完成后，您可能希望提交拉取请求，以便维护人员对其进行审查。

在提交拉取请求之前，请确保您仔细阅读此清单，以便维护人员更容易接受您提出的更改：

  • [ ] 确保任何更改或新功能都有单元和/或集成测试。

    如果未编写测试，则会为您的 PR 分配一个名称为 Needs Test Coverage 的标签。

  • [ ] 确保单元测试覆盖率不会降低。

    pytest -xv --cov=celery --cov-report=xml --cov-report term。 您可以在此处查看当前的测试覆盖率：https://codecov.io/gh/celery/celery

  • [ ] 针对代码运行 pre-commit。 以下命令有效

    和等价物：

    $ pre-commit run --all-files
$ tox -e lint
  • [ ] 构建 api 文档以确保一切正常。 以下命令有效

    和等价物：

    $ make apicheck
$ cd docs && sphinx-build -b apicheck -d _build/doctrees . _build/apicheck
$ tox -e apicheck
  • [ ] 构建配置检查。 以下命令有效

    和等价物：

    $ make configcheck
$ cd docs && sphinx-build -b configcheck -d _build/doctrees   . _build/configcheck
$ tox -e configcheck
  • [ ] 运行 bandit 以确保没有安全问题。 以下命令有效

    和等价物：

    $ pip install -U bandit
$ bandit -b bandit.json celery/
$ tox -e bandit
  • [] 为每个 Python 版本运行单元和集成测试。 以下命令有效

    和等价物：

    $ tox -v

  • [ ] 在任何新的或修改的导入上确认 isort：

    $ isort my_module.py --diff

创建拉取请求很容易，它们还可以让您跟踪您的贡献进度。 阅读 GitHub 指南中的 拉取请求 部分以了解这是如何完成的。

您还可以按照此处概述的步骤将拉取请求附加到现有问题：https://bit.ly/koJoso

您还可以使用 hub 创建拉取请求。 示例：https://theiconic.tech/git-hub-fbe2e13ef4d1

状态标签

有 不同的标签 用于轻松管理 github 问题和 PR。 这些标签中的大多数都可以轻松地将每个问题与重要细节进行分类。 例如，您可能会在问题或 PR 上看到 Component:canvas 标签。 Component:canvas 标签表示问题或 PR 对应于画布功能。 这些标签是由维护者设置的，在大多数情况下，外部贡献者不应该担心它们。 这些标签的子集前面带有 Status:。 通常 Status: 标签显示问题或 PR 需要的重要操作。 以下是此类状态的摘要：

  • 状态：无法重现

    一名或多名 Celery 核心团队成员无法重现该问题。

  • 状态：已确认

    问题或 PR 已由一名或多名 Celery 核心团队成员确认。

  • 状态：重复

    重复的问题或 PR。

  • 状态：需要反馈

    一位或多位 Celery 核心团队成员要求就该问题或 PR 提供反馈。

  • 状态：有测试用例

    已确认问题或 PR 包含测试用例。 这对于为任何新功能或错误修复正确编写测试尤为重要。

  • 状态：进行中

    PR仍在进行中。

  • 状态：无效

    报告的问题或 PR 对项目无效。

  • 状态：需要文件

    PR 不包含提议的功能或错误修复的文档。

  • 状态：需要变基

    PR 没有用 master 重新定位。 在将 PR 合并到 master 以解决任何合并冲突之前，重新设置 PR 是非常重要的。

  • 状态：需要测试覆盖

    Celery 使用 codecov 来验证代码覆盖率。 请确保 PR 不会降低代码覆盖率。 该标签将标识需要代码覆盖的 PR。

  • 状态：需要测试用例

    问题或 PR 需要一个测试用例。 测试用例可以是重现问题的最小代码片段，也可以是重现所报告问题的详细说明和配置值集。 如果可能，可以将测试用例以 PR 的形式提交给 Celery 的集成套件。 在修复错误之前，测试用例将被标记为失败。 当 Celery 的集成套件无法运行测试用例时，最好在问题本身中进行描述。

  • 状态：需要验证

    此标签用于通知其他用户我们需要验证报告者提供的测试用例和/或我们需要将测试包含在我们的集成套件中。

  • 状态：不是错误

    已确定报告的问题不是错误。

  • 状态：不会修复

    已经决定这个问题不会被修复。 遗憾的是，Celery 项目没有无限的资源，有时必须做出这个决定。 尽管如此，即使问题或 PR 被标记为 Status: Won't Fix，也邀请任何外部贡献者提供帮助。

  • 状态：为我工作

    一名或多名 Celery 核心团队成员已确认所报告的问题适用于他们。


编码风格

您可能应该能够从周围的代码中选择编码风格，但了解以下约定是个好主意。

  • 所有 Python 代码都必须遵循 PEP 8 准则。

:pypi:`pep8` 是一个实用程序，可用于验证您的代码是否遵循约定。

  • 文档字符串必须遵循 PEP 257 约定，并使用以下样式。

    这样做：

    def method(self, arg):
    """Short description.

    More details.

    """

    或：

    def method(self, arg):
    """Short description."""

    但不是这个：

    def method(self, arg):
    """
    Short description.
    """

  • 行不应超过 78 列。

    您可以通过设置 textwidth 选项在 vim 中强制执行此操作：

    set textwidth=78

    如果遵守这一限制会降低代码的可读性，那么您还有一个字符要继续。 这意味着 78 是软限制，79 是硬限制 :)

  • 进口订单

    • Python 标准库（import xxx）

    • Python 标准库（from xxx import）

    • 第三方包。

    • 当前包中的其他模块。

    或者在使用 Django 的代码的情况下：

    • Python 标准库（import xxx）

    • Python 标准库（from xxx import）

    • 第三方包。

    • Django 包。

    • 当前包中的其他模块。

    在这些部分中，导入应按模块名称排序。

    示例：

    import threading
import time

from collections import deque
from Queue import Queue, Empty

from .platforms import Pidfile
from .utils.time import maybe_timedelta

  • 不得使用通配符导入（from xxx import *）。

  • 对于 Python 2.5 是最早支持版本的发行版，适用附加规则：

    • 必须在每个模块的顶部启用绝对导入：

      from __future__ import absolute_import

    • 如果模块使用 with 语句并且必须与 Python 2.5 兼容（celery 不是），那么它还必须启用：

      from __future__ import with_statement

    • 每个未来的导入都必须在自己的行上，因为较旧的 Python 2.5 版本不支持在同一未来导入行上导入多个功能：

      # Good
from __future__ import absolute_import
from __future__ import with_statement

# Bad
from __future__ import absolute_import, with_statement

    （请注意，如果包不包含对 Python 2.5 的支持，则此规则不适用）

  • 请注意，当发行版不支持低于 2.5 的 Python 版本时，我们使用“新式”相对导入

    这需要 Python 2.5 或更高版本：

    from . import submodule


贡献需要额外库的功能

某些功能（例如新的结果后端）可能需要用户必须安装的其他库。

为此，我们使用 setuptools extra_requires，并且必须添加所有需要第三方库的新可选功能。

  1. 在 requirements/extras 中添加新的需求文件

    对于 Cassandra 后端，这是 requirements/extras/cassandra.txt，文件如下所示：

    pycassa

    这些是 pip 需求文件，因此您可以使用版本说明符，并且多个包由换行符分隔。 一个更复杂的例子可能是：

    # pycassa 2.0 breaks Foo
pycassa>=1.0,<2.0
thrift

  2. 修改【X7X】【X11X】

    添加需求文件后，需要将其作为选项添加到extras_require部分的setup.py中：

    extra['extras_require'] = {
    # ...
    'cassandra': extras('cassandra.txt'),
}

  3. 记录 docs/includes/installation.txt 中的新功能

    您必须将您的功能添加到 docs/includes/installation.txt 的 捆绑包 部分的列表中。

    对此文件进行更改后，您需要渲染发行版 README 文件：

    $ pip install -U requirements/pkgutils.txt
$ make readme

这就是所有需要做的事情，但请记住，如果您的功能添加了额外的配置选项，那么这些需要记录在 docs/configuration.rst 中。 此外，所有设置都需要添加到 celery/app/defaults.py 模块中。

结果后端需要在 docs/configuration.rst 文件中有一个单独的部分。


联系人

这是一个可以联系有关官方 git 存储库、PyPI 包的问题的人员列表，请阅读文档页面。

如果问题不是紧急情况，那么最好 报告问题 。

提交者

阿西夫·赛义夫·乌丁

github
https://github.com/auvipy
推特
https://twitter.com/#!/auvipy


德米特里·马林诺夫斯基

github
https://github.com/malinoff
推特
https://twitter.com/__malinoff__


Ionel Cristian Mărieș

github
https://github.com/ionelmc
推特
https://twitter.com/ionelmc


乔苏·巴兰德拉诺·科罗内尔

github
https://github.com/xirdneh
推特
https://twitter.com/eusoj_xirdneh


网站

Celery 项目网站由

毛罗·罗科

github
https://github.com/fireantology
推特
https://twitter.com/#!/fireantology

设计者：


扬·亨里克·赫尔默斯

网络
http://www.helmersworks.com
推特
https://twitter.com/#!/helmers


套餐

billiard

包含最终将合并到 Python 标准库中的改进的多处理分支。

混帐
https://github.com/celery/billiard
CI
https://travis-ci.org/#!/celery/billiard/
视窗CI
https://ci.appveyor.com/project/ask/billiard
PyPI
:pypi:`台球`


django-celery-beat

使用 Django ORM 的具有管理界面的数据库支持的周期性任务。

混帐
https://github.com/celery/django-celery-beat
CI
https://travis-ci.org/#!/celery/django-celery-beat
视窗CI
https://ci.appveyor.com/project/ask/django-celery-beat
PyPI
:pypi:`django-celery-beat`


django-celery-results

将任务结果存储在 Django ORM 中，或使用 Django 缓存框架。

混帐
https://github.com/celery/django-celery-results
CI
https://travis-ci.org/#!/celery/django-celery-results
视窗CI
https://ci.appveyor.com/project/ask/django-celery-results
PyPI
:pypi:`django-celery-results`


librabbitmq

用 C 编写的非常快的 Python AMQP 客户端。

混帐
https://github.com/celery/librabbitmq
PyPI
:pypi:`librabbitmq`


cell

演员库。

混帐
https://github.com/celery/cell
PyPI
:pypi:`细胞`


cyme

分布式 Celery 实例管理器。

混帐
https://github.com/celery/cyme
PyPI
:pypi:`cyme`
文档
https://cyme.readthedocs.io/


释放程序

更新版本号

版本号必须在三个地方更新：

  • celery/__init__.py
  • docs/include/introduction.txt
  • README.rst


可以使用 [bumpversion 命令行工具] (https://pypi.org/project/bumpversion/) 处理对先前文件的更改。 相应的配置位于 .bumpversion.cfg 中。 要进行必要的更改，请运行： 

$ bumpversion

更改这些文件后，必须渲染 README 文件。 有一个脚本可以将 sphinx 语法转换为通用的 reStructured Text 语法，并且 make target readme 为您执行此操作： 

$ make readme

现在提交更改： 

$ git commit -a -m "Bumps version to X.Y.Z"

并制作一个新的版本标签： 

$ git tag vX.Y.Z
$ git push --tags

释放

制作新的公共稳定版本的命令： 

$ make distcheck  # checks pep8, autodoc index, runs tests and more
$ make dist  # NOTE: Runs git clean -xdf and removes files not in the repo.
$ python setup.py sdist upload --sign --identity='Celery Security Team'
$ python setup.py bdist_wheel upload --sign --identity='Celery Security Team'

如果这是一个新的发布系列，那么您还需要执行以下操作：



取自“https://cainiaojiaocheng.com/index.php?title=Celery/docs/latest/contributing&oldid=25441”
Powered by MediaWiki