跳到主要内容

维护包

重要提示​

conda-forge 上的包是不可变的​

根据政策，我们不允许编辑或删除 conda-forge 上的包。这项政策非常重要，因为它提高了使用 conda-forge 频道创建的 conda 环境的可靠性和可重复性。请注意，由于这项政策，我们的上传脚本将拒绝上传已存在于 conda-forge 频道上的包。

如果您需要删除一个包，请参阅关于标记包为损坏的章节。

Fork 和拉取请求​

所有维护者都获得了他们维护的 feedstock 的推送权限。这意味着维护者可以在主仓库中创建分支。对于更新，不鼓励在主仓库中使用分支，因为：

  1. CI 在分支和 PR 上都会运行。

    这浪费了 CI 资源

  2. 分支会自动发布。

    这意味着如果您将版本更新推送到分支，然后创建一个 PR，conda 包将在 PR 合并之前发布到 anaconda.org。

重要提示

由于这些原因，我们要求维护者 fork feedstock 到他们的个人帐户，推送到 fork 中的一个分支，然后向 conda-forge 仓库打开一个 PR。

推送到 regro-cf-autotick-bot 分支​

当一个包的新版本在 PyPI/CRAN/... 上发布时，我们有一个机器人会自动为 feedstock 创建版本更新。在大多数情况下，您只需合并这个 PR，它应该包含所有更改。当上游发生某些更改时，例如依赖项，您仍然需要对创建的 PR 进行更改。作为 feedstock 维护者，您不必为此创建一个新的 PR，只需推送到机器人创建的分支即可。有两种替代方案可以将内容推送到机器人的分支：

  1. 手动设置 git 远程仓库

    • 克隆 conda-forge feedstock 仓库

    • 添加机器人的远程仓库：git remote add regro-cf-autotick-bot [email protected]:regro-cf-autotick-bot/<package>-feedstock.git

      重要提示

      无法使用 git:// 协议推送到 GitHub 仓库。有关在使用 https:// 协议时启用 双因素身份验证 的说明，请参阅 我应该使用哪个远程 URL？。

    • 获取远程仓库：git fetch regro-cf-autotick-bot

    • 检出 PR 的分支，如果这是唯一具有该名称分支的远程仓库，git 应该会自动将其链接到 regro-cf-autotick-bot 远程仓库。

    • 如果存在多个具有此分支名称的远程仓库，您需要先检出远程分支，然后将其转换为本地分支：git checkout regro-cf-autotick-bot/<branch> && git checkout -b <branch>

    • 在该分支上提交和推送，如果远程仓库未正确设置，请使用 git push -u regro-cf-autotick-bot <branch>。

  2. 使用 Github 的 hub 工具（conda-forge 自带！conda install hub -c conda-forge）

    • 克隆 conda-forge feedstock 仓库
    • 使用远程仓库检出正确的分支：hub pr checkout 12，其中 12 是 PR 的 ID。
    • 在此分支上提交和推送，远程仓库会自动设置为推送到 regro-cf-autotick-bot 的 fork。

regro-cf-autotick-bot 如何创建自动版本更新？​

regro-cf-autotick-bot 在循环中持续搜索任何 PyPI 版本发布、GitHub 版本发布以及任何其他版本来源，以查找任何更新。循环中执行的源代码来自 cf-scripts 仓库，其中包含检测版本和提交 PR 的代码。访问 cf-scripts 以阅读更多相关信息。

机器人通过检查上游版本创建更新，并将始终更新 recipe 元数据 中的 source 部分和构建版本。作为一项实验性功能，autotick 机器人还可以配置为验证或更新 Grayskull 兼容 recipe 的需求。这可能有助于维护具有频繁需求更改或特定需求版本固定的包，但是此功能尚未经过广泛验证，提出的更新应进行审查。（请参阅 conda-forge.yml 中的 bot 部分）

有时机器人可能需要几个小时才能搜索到这些更新。您还可以查看 版本更新状态，了解所有待处理的版本更新。这些版本更新正在等待处理，可能是因为找到了更新的版本，但尚未打开 PR，或者是因为机器人在创建 PR 时可能遇到了错误。如果您在此处找不到某个版本，那么很可能机器人也找不到它。

当包 feedstock 有三个或更多个打开的版本更新 PR 时，机器人会停止创建版本更新 PR。包的维护者应关闭或合并这些 PR，以便机器人将来能够正确地进行版本更新。

更新包的工作流程示例​

这里我们假设您想要更新 feedstock <feedstock>。Feedstock 是一个占位符，例如可以替换为 numpy-feedstock。

  1. Fork feedstock

    在您可以提交您的第一个 PR 之前，您必须 fork conda-forge 的 feedstock。

    • 在您喜欢的 Web 浏览器中导航到 https://github.com/conda-forge/并单击 fork 按钮。
    • 您现在在 https://github.com/<your-github-id>/<feedstock> 中拥有了 feedstock 的克隆副本，并且在您的控制之下。
    • 通过使用 git clone https://github.com/<your-github-id>/<feedstock> 从您的计算机连接到 feedstock。

  2. 将您的 fork 与 conda-forge 的 feedstock 同步

    如果您在一段时间前 fork 了，并且您的 fork 缺少 conda-forge feedstock 的提交，则此步骤是必需的。

    • 确保您在 main 分支上：git checkout main
    • 使用 git remote add upstream https://github.com/conda-forge/<feedstock> 注册 conda-forge 的 feedstock
    • 使用 git fetch upstream 获取最新更新
    • 将最新更改拉入您的 main 分支：git rebase upstream/main

  3. 在新分支中创建您的更改

    现在您可以更新 recipe 了

    • 创建并切换到新分支：git checkout -b <branch-name>。<branch-name> 可以是例如 update_1_0_1。
    • 在本地进行更改
    • 查看您的更改，然后使用 git add <changed-files>。其中 <changed-files> 是您更改的文件名的空格分隔列表。
    • 通过 git commit -m <commit-msg> 创建提交，其中 <commit-msg> 可以是 updated feedstock to version 1.0.1

  4. 将您的更改推送到 GitHub 并提出 PR

    • 将带有更改的分支推送到您在 GitHub 上的 fork：git push origin <branch-name>
    • 通过 Web 界面创建拉取请求，方法是使用 Web 浏览器导航到 https://github.com/<your-github-id>/<feedstock> 并单击 create pull request 按钮。

更新 recipe​

更新 recipe 时，请遵循以下准则

  1. 更新 recipe 时，始终使用 feedstock 的 fork。
  2. 当包的版本未更改，但其他元数据或 recipe 的其他部分已更改时，将构建号增加 1。
  3. 在发布包的新版本时，将构建号重置为 0。

重新渲染 feedstock​

重新渲染是 conda-forge 更新所有 feedstock 通用文件（例如 README、CI 配置、固定的依赖项）的方式。

重新渲染可以通过两种方式完成

  1. 通过添加注释 @conda-forge-admin please rerender，使用 Web 服务在云端运行 conda-smithy（请参阅管理员 Web 服务）。
  2. 在您的机器上本地运行 conda-smithy（请参阅本地使用 conda-smithy 重新渲染）。

本地使用 conda-smithy 重新渲染​

第一步是在您的 root 环境中安装 conda-smithy。

conda install -c conda-forge conda-smithy

提交所有更改，并从 feedstock 的根目录中键入

conda smithy rerender -c auto

可以选择手动提交更改。为此，请从命令中删除 -c auto。

何时重新渲染​

当 feedstock 的以下部分发生更改时，我们需要重新渲染

  • 平台配置（skip 部分）。
  • yum_requirements.txt 或 conda-forge.yml。
  • 由于新的 Python、NumPy、PERL、R 等版本，构建矩阵中的更新。
  • 影响 feedstock 的 conda-forge pinning 中的更新。
  • feedstock 配置更新将修复的构建问题（在 Zulip 上关注我们以了解这些问题）。

为新发布的 Python 版本更新​

当发布新的 Python 版本（例如 3.11）时，将触发自动迁移过程，该过程最终将使 @regro-cf-autotick-bot 自动打开所有 feedstock 的拉取请求，更新其 CI 设置以在构建矩阵中包含新的 Python 版本。在验证 PR 构建通过后，可以简单地合并该自动 PR 以为新的 Python 版本推出包。但是，此过程需要时间，并且不会同时向所有 feedstock 打开拉取请求，以免 CI 过载。可以在迁移状态页面上跟踪迁移的当前状态，维护者可以在此处验证他们的 feedstock 是否列在 AWAITING-PR 下拉列表中。

在本地测试更改​

如果您的系统上安装了 docker，您可以在与我们的 CI 构建相同的设置下，在您的机器上本地测试构建。

如果您想在本地构建和测试 feedstock 的更新，请转到根 feedstock 目录并运行

python build-locally.py

这将提示您选择 .ci_support/ 中的一个 *.yaml 配置文件。请注意，需要 shyaml 从这些文件中解析 docker_image。否则，构建将使用默认的 docker_image。

或者，您可以提前指定要使用的配置，例如（假设您希望在 Linux 上构建和测试 python 3.6，并且 .ci_support/linux_python3.6.yaml 中存在这样的配置文件）

python build-locally.py linux_python3.6

请注意，对于长构建日志，可以执行

python build-locally.py 2>&1 | tee log.txt

将其保存在文本文件中以供将来检查。

构建完成后，您可以在 feedstock 的 build_artifacts 目录中找到完成的包，该目录可以用作频道。

要使用 conda 创建一个新环境 my-new-env，其中将包含新构建的包 my-package，请运行

conda create -n my-new-env -c "file://${PWD}/build_artifacts" my-package

如果新构建的包依赖于另一个包才能工作，即 other-package，并且该包在 conda-forge 频道上可用，例如，您可以运行

conda create -n my-new-env -c "file://${PWD}/build_artifacts" -c conda-forge my-package other-package

从 CI 下载预构建的包​

feedstock 的一个简洁功能是能够将包上传到 CI 提供商进行测试。这在尝试 PR 中构建的包时非常有用。但是您首先需要下载这些预构建的包。

要下载预构建的包，请按照以下步骤操作

  • 从您的 PR 开始，导航到 CI。
  • 打开与您要下载的包对应的日志。
  • 在此日志中找到指向 artifacts produced 的链接。
  • 从出现的已发布工件列表中下载您需要的存档。
  • 解压缩并提取所需的包。

移除损坏的软件包​

有时会发生错误，损坏的软件包最终会被上传到 conda-forge 频道。

如果唯一的问题出在软件包元数据中，我们可以使用 repo data patches feedstock 直接对其进行修补。 如果是这种情况，应遵循以下通用指南

  1. 更新 feedstocks recipe 以确保未来的构建不会在新版本号中传播该问题。
  2. 请在那里创建一个 PR 以添加补丁。补丁应尽可能详细地指定软件包生成时的版本和时间。它可以使用以下信息
  • 当前时间戳，您可以使用 python -c "import time; print(f'{time.time():.0f}000')" 生成它。
  • 要影响的软件包的问题版本和构建号。

如果软件包的实际内容已损坏，则以下步骤将从 main 频道中移除损坏的软件包

  1. 在 anaconda.org 上找到损坏文件的路径，方法是搜索 conda-forge 软件包并切换到文件选项卡。
  2. Fork conda-forge/admin-requests 并在 requests 目录中添加一个新的 YML 文件。
  3. 将损坏的文件添加到新的 YML 文档中。有关示例文件，请参见 examples/example-broken.yml。
  4. 打开一个新的 PR。合并后，机器人会将所有列出的文件标记为损坏，从而有效地从频道中移除它们。

归档 feedstocks​

如果一个软件包不再维护，conda-forge 将归档该仓库。归档的仓库将不再接受 PR 和 issue，这会阻止人们和 regro-cf-autotick-bot 更新软件包（例如，重新渲染 feedstock 以支持新的 Python 版本）。请注意，这不会移除现有的软件包，它们仍然可用。

如果您认为应该归档某个 feedstock，请执行以下操作

  1. 在 feedstock 上提出一个 issue，询问是否可以归档它（抄送维护者团队和 @conda-forge/core）
  2. Fork conda-forge/admin-requests 并在 requests 目录中添加一个新的 yml 文件，命名为 <package>-archive.yml 并包含
action: archive
feedstocks:
  - <name of the feedstock to archive without the -feedstock suffix>

示例

action: archive
feedstocks:
  - or-datasets

您可以在同一请求中列出多个 feedstock。

  1. 打开一个 PR 并交叉引用在步骤 1 中提出的 issue。

更新维护者列表​

feedstock 的维护者列表记录在 recipe 本身中。可以通过在 feedstock 仓库中打开一个 issue 并使用以下标题来添加新的维护者

@conda-forge-admin，请添加用户 @username

其中 username 是要添加的新维护者的用户名。将自动创建一个 PR，如果没有任何维护者处于活动状态，维护者或 core 团队的成员可以合并此 PR 以添加用户。要联系 core，请在评论中提及 @conda-forge/core 来 ping 他们，或者如果您在一段时间内没有收到回复或刚接触 conda-forge，请通过社区 Zulip 聊天室 联系他们。

注意

此 PR 旨在跳过构建软件包。请不要修改它或调整提交消息。

这不是开始帮助 feedstock 的推荐方式。如果您有兴趣帮助处理特定的 recipe，最好从提交包含新版本或修复程序的 PR 开始。这样，您可以获得对您工作的反馈，并了解 feedstock 的一些历史背景。

一旦您与维护者建立了工作关系，您可以请求他们将您添加到 feedstock 团队。然后他们可以使用此命令将您添加到团队。关于如何添加新维护者，没有任何官方要求，因此可能需要一段时间才能就何时添加新维护者达成共识。不要因此而气馁，请继续贡献！

任何人都可以自由地打开 PR！！！感谢您的时间和努力！！！

有关示例，请参见 此 issue。

维护多个版本​

如果您想维护软件包的多个版本，可以使用 feedstock 上的分支。为此

  • Fork 您的 feedstock 并创建一个有意义的分支名称（例如，v1.X 或 v1.0）。
  • 对 recipe 进行必要的更改并重新渲染 feedstock。
  • 然后将此分支从您的 fork 推送到上游 feedstock。我们的 CI 服务将自动构建除默认分支之外的任何分支。