为Supervision贡献 🛠️¶
感谢您对贡献Supervision感兴趣！
我们正在积极改进这个库，以减少您解决常见计算机视觉问题所需的工作量。
行为准则¶
请阅读并遵守我们的行为准则。该文件概述了我们项目中所有参与者应遵守的行为规范。
目录¶
贡献指南¶
我们欢迎对以下内容的贡献：
- 向库中添加新功能（下方有指引）。
- 改进我们的文档并添加示例，以明确如何利用supervision库。
- 在项目中报告错误和问题。
- 提交新功能请求。
- 提高我们的测试覆盖率。
贡献功能 ✨¶
Supervision旨在提供通用工具来解决各种问题。因此，我们专注于那些能对广泛项目产生影响的贡献。
例如，在计算机视觉中，统计图像中任意位置穿过某条线的物体数量是一个常见问题，但统计物体在行进75%距离时才穿过线条的情况则实用性较低。
在贡献新功能之前，请考虑提交一个Issue来讨论该功能，以便社区可以参与并提供帮助。
如何贡献变更¶
首先，将此仓库fork到您自己的GitHub账户。点击supervision仓库右上角的"fork"按钮开始：
然后，运行 git clone 将项目代码下载到您的计算机上。
您还应该将roboflow/supervision设置为"上游"远程（即告诉git这个Supervision参考仓库是您fork的来源）：
使用 git checkout 命令切换到新分支：
您为分支选择的名称应描述您想要进行的更改，并以适当的前缀开头：
feat/: 用于新功能 (例如,feat/line-counter)fix/: 用于错误修复（例如，fix/memory-leak）docs/: 用于文档变更（例如：docs/update-readme）chore/: 用于日常任务、维护或工具变更（例如chore/update-dependencies）test/: 用于添加或修改测试（例如，test/add-unit-tests）refactor/: 用于代码重构（例如：refactor/simplify-algorithm）
对项目代码进行任何你想要的修改，然后运行以下命令提交你的更改：
git add -A
git commit -m "feat: add line counter functionality"
git push -u origin <your_branch_name>
使用常规的提交信息来清晰地描述您的更改。格式如下：
常见类型包括：
- 功能: 新增特性
- 修复: 一个错误修复
- docs: 仅文档变更
- style: 不影响代码含义的更改（空格、格式化等）
- 重构：既不修复错误也不添加功能的代码更改
- perf: 提升性能的代码变更
- test: 添加缺失的测试或修正现有的测试
- chore: 对构建流程或辅助工具和库的更改
然后，回到您分叉的supervision仓库，点击"Pull Requests"，再点击"New Pull Request"。
在提交PR之前，请确保base分支是develop。
在下一页，检查您的更改，然后点击"Create pull request"：
接下来，为您的拉取请求撰写描述，然后再次点击"Create pull request"提交审核：
创建新函数时，请确保您具备以下条件：
- 函数及其所有参数的文档字符串。
- 该函数的单元测试。
- 该函数的文档中的示例。
- 在我们的文档中创建了一个条目，用于自动生成该函数的文档。
- 请尽可能分享一个包含最少代码的Google Colab来测试新功能或重现PR。请确保Google Colab可以无障碍访问。
当您提交Pull Request时，cla-assistant GitHub机器人会要求您签署贡献者许可协议(CLA)。我们只能回应已签署项目CLA的贡献者的PR。
所有拉取请求将由项目维护者进行审核。我们会提供反馈意见，并在必要时要求修改。
PR在合并前必须通过所有测试和代码规范检查。
贡献者安装指南¶
在开始项目工作之前，请设置您的开发环境：
-
克隆您fork的项目（推荐使用develop分支的浅克隆）：
选项A：推荐给大多数贡献者（develop分支的浅克隆）：
将
YOUR_USERNAME替换为您的GitHub用户名。注意：使用
--depth 1会创建一个历史记录最少的浅克隆，而-b develop确保您从开发分支开始。这显著减少了下载大小，同时提供了贡献所需的一切。选项B：完整仓库克隆（如果您需要完整历史记录）：
-
创建并激活虚拟环境：
-
安装
uv:按照 uv 安装页面 上的说明进行操作。
-
安装项目依赖：
-
运行pytest以验证设置：
🎨 代码风格与质量¶
预提交工具¶
本项目使用pre-commit工具来维护代码质量和一致性。在提交拉取请求或进行任何提交之前，运行pre-commit工具以确保您的更改符合项目指南非常重要。
此外，我们已将pre-commit GitHub Action集成到工作流程中。这意味着每次打开pull request时，都会自动执行pre-commit检查，从而简化代码审查流程并确保所有贡献都符合我们的质量标准。
要运行pre-commit工具，请按照以下步骤操作：
-
通过运行以下命令安装pre-commit：
uv pip install -r pyproject.toml --extra dev。该命令不仅会安装pre-commit，还会安装项目的所有依赖项和开发依赖项 -
安装完 pre-commit 后，请导航至项目的根目录。
-
运行命令
pre-commit run --all-files。这将针对修改过的文件执行项目配置的pre-commit钩子。如果发现任何问题，pre-commit工具会提供如何解决这些问题的反馈。进行必要的修改并重新运行pre-commit命令，直到所有问题都得到解决。 -
您还可以通过执行
pre-commit install将pre-commit安装为git钩子。每次执行git commit时，pre-commit都会自动为您运行。
文档字符串¶
supervision中的所有新函数和类都应包含文档字符串。这是将任何新函数和类添加到库中的先决条件。
supervision遵循Google Python文档字符串风格。在为您的贡献编写文档字符串时，请参考该风格指南。
类型检查¶
目前，还没有使用mypy进行类型检查。参见issue。
📝 文档¶
supervision的文档存储在名为docs的文件夹中。该项目文档是使用mkdocs构建的。
要运行文档，请使用uv pip install -r pyproject.toml --extra dev --extra docs安装项目依赖。然后运行mkdocs serve启动文档服务器。
你可以在mkdocs网站上了解更多关于mkdocs的信息。
🧑🍳 使用指南¶
我们一直在寻找新的示例和教程来添加到supervision文档中。如果您有认为对他人有帮助的用例，请提交包含您示例的PR。以下是提交新示例的一些指导原则：
- 在
docs/notebooks文件夹中创建一个新的笔记本。 - Add a link to the new notebook in
docs/theme/cookbooks.html. Make sure to add the path to the new notebook, as well as a title, labels, author and supervision version. - 使用Count Objects Crossing the Line示例作为新示例的模板。
- 冻结您正在使用的
supervision版本。 - 在笔记本顶部放置一个合适的"在Colab中打开"按钮。您可以在前面提到的
Count Objects Crossing the Line教程中找到此类按钮的示例。 - Notebook应该是自包含的。如果您依赖外部数据（视频、图像等）或库，请在notebook中包含下载和安装命令。
- 用适当的注释对代码进行标注，包括指向描述您所用工具的文档链接。
🧪 测试¶
pytests 用于运行我们的测试。
📄 许可证¶
通过贡献代码，您同意您的贡献将按照MIT许可证的条款进行授权。