评估变更¶
大多数情况下，您的变更会影响格式化和/或性能。量化这些变更很困难，因此我们提供了一些工具来帮助简化此过程。
建议您在提交 PR 之前评估 Black 格式化修改造成的可量化变更。考虑一下变更是否会对已经“使用 Black 格式化”的项目造成足以令人沮丧的破坏。
diff-shades¶
diff-shades 是一款工具，它会在多个开源项目上运行 Black，并记录结果。diff-shades 的主要亮点功能是能够比较两个 Black 版本。这非常有用，因为它让我们可以查看将要发生的具体变更，例如合并特定 PR。
有关更多信息，请参阅 diff-shades 文档.
CI 集成¶
diff-shades 也是 PR 上“diff-shades 结果比较...”/“diff-shades 报告无变更...”评论背后的工具。该项目有一个 GitHub Actions 工作流程，根据以下规则分析和比较两个 Black 版本。
基线版本 |
目标版本 |
|
|---|---|---|
在 PR 上 |
|
合并了 |
在推送 (仅限 main) |
最新 PyPI 版本 |
推送的提交 |
对于 main 的推送，只有一个名为 preview-changes 的分析作业，其中所有项目的预览风格都会被使用。
对于 PR，它们还有一个分析作业：assert-no-changes。它与 preview-changes 相似，但使用稳定代码风格运行。如果进行了变更，它将失败。这确保了代码不会在同一年内根据 Black 的稳定性策略再次格式化。
此外，对于 PR，将发布一条 PR 评论，其中包含预览变更的摘要和指向更多信息的链接。如果存在预先存在的 diff-shades 评论，则将在下次在相同 PR 上触发工作流程时更新它。
注意
如果在分析文件时无法格式化，preview-changes 作业将只会在故意情况下失败。否则，失败表明工作流程存在错误。
工作流程在完成时会上传几个工件
原始分析 (.json)
HTML 差异 (.html)
.pr-comment.json(如果由 PR 触发)
最后一个由 diff-shades-comment 工作流程下载，不应在本地下载。HTML 差异在基于推送的场景下非常有用，因为没有 PR 可以发布评论。分析存在只是为了您可能想要使用收集到的数据在本地进行进一步分析。