Manim 开发流程¶

首次贡献者须知¶

安装 Git

有关说明，请参阅 https://git-scm.cn/。
派生项目 (Fork the project)

前往 https://github.com/ManimCommunity/manim 并点击“fork”按钮，为你的工作创建一个项目副本。你需要一个 GitHub 账户。这将允许你稍后向 ManimCommunity 仓库发起“拉取请求”(PR)。
将你的派生项目克隆到本地计算机
```
git clone https://github.com/<your-username>/manim.git
```
GitHub 将提供 SSH (git@github.com:<your-username>/manim.git) 和 HTTPS (https://github.com/<your-username>/manim.git) URL 用于克隆。如果你已设置 SSH 密钥，可以使用 SSH。

警告

请勿克隆 ManimCommunity 仓库。你必须克隆你自己的派生项目。
切换目录以进入项目文件夹
```
cd manim
```

添加上游仓库 ManimCommunity

git remote add upstream https://github.com/ManimCommunity/manim.git

现在，git remote -v 应该显示两个名为的远程仓库
- origin，你的派生仓库
- upstream，ManimCommunity 仓库
安装 Manim
- 请遵循我们的安装说明中的步骤来安装 Manim 的系统依赖项。我们还建议安装 LaTeX 发行版。
- 我们建议使用 Poetry 来管理你的 Manim 开发者安装。Poetry 是一个用于 Python 中依赖管理和打包的工具。它允许你声明项目所依赖的库，并为你管理（安装/更新）它们。此外，Poetry 提供了一个简单的接口来管理虚拟环境。
  
  如果你也选择使用 Poetry，请遵循Poetry 的安装指南将其安装到你的系统上，然后从你克隆的仓库中运行 poetry install。Poetry 将安装 Manim，并创建和进入一个虚拟环境。你始终可以通过运行 poetry shell 重新进入该环境。
- 如果你想安装 pyproject.toml 文件中 [tool.poetry.extras] 部分定义的额外依赖项，可以通过传递 -E 标志来完成，例如 poetry install -E jupyterlab -E gui。
- 如果你决定不使用 Poetry，可以通过运行 python3 -m pip install . 通过 pip 安装 Manim。请注意，由于我们的开发基础设施基于 Poetry，我们目前不支持通过 pip 进行可编辑安装，因此每次更改源代码时都必须重新运行此命令。
注意

以下步骤假定你选择安装并使用 Poetry。
安装 Pre-Commit
```
poetry run pre-commit install
```
这将确保在开发过程中，你的每次提交都根据我们的代码检查器和格式化工具 black、flake8、isort 和 codespell 进行正确格式化。

现在你已准备好为 Manim 工作！

开发你的贡献¶

检出你本地仓库的 `main` 分支，并将 ManimCommunity（即 `upstream`）的最新更改拉取到你的本地仓库
```
git checkout main
git pull --rebase upstream main
```
为你想要处理的更改创建一个分支，而不是直接在本地 `main` 分支上工作
```
git checkout -b <new branch name> upstream/main
```
这确保你可以轻松地通过第一步更新本地仓库的 `main` 分支，并切换分支来处理多个功能。
编写出色的代码！

你已准备好在本地仓库的分支中进行更改。你可以使用 git add . 添加当前目录中已更改的本地文件，或者使用以下命令添加特定文件
```
git add <file/directory>
```
并使用 git commit 将这些更改提交到你的本地历史记录。如果你已经安装了 pre-commit，只有当所有钩子都通过时，你的提交才会成功。

提示

在编写提交消息时，强烈建议你遵守这些指南。
添加新测试或更新现有测试。

根据你的更改，你可能需要更新或添加新测试。对于新功能，你的拉取请求必须包含测试。我们的测试系统的详细信息在测试指南中有所解释。
更新文档字符串和文档

更新你更改的任何函数或类的文档字符串（三引号内的文本），并将其包含在你添加的任何新函数中。有关我们偏好的代码文档方式的更多信息，请参阅文档指南。文档字符串的内容将在参考手册中呈现。

提示

使用 Sphinx 的 Manim 指令 将示例添加到文档中！

就你在本地机器上的开发而言，这些是你应该遵循的主要步骤。

完善更改并提交拉取请求¶

一旦你准备好与社区分享你的本地更改以便讨论，请按照以下步骤打开拉取请求。拉取请求向 ManimCommunity 组织表明：“这是我编写的一些更改；我认为你们值得维护它们。”

注意

你不必在打开拉取请求（PR）时完成所有内容（代码/文档/测试）。如果 PR 仍在开发中，请将其标记为草稿。社区开发者仍然能够审查更改、讨论尚未实现的功能并提供建议；但是，你的 PR 越完整，合并速度就越快。

更新 GitHub 上的派生项目以反映你的本地更改
```
git push -u origin <branch name>
```
这样做会在你的远程派生项目 origin 上创建一个新分支，其中包含你本地仓库的内容，并推送到 GitHub。在后续推送中，此本地分支将跟踪 origin 分支，并且 git push 就足够了。
在 GitHub 上创建拉取请求 (PR)。

为了让 ManimCommunity 开发团队了解你的更改，你可以从你的派生项目向 ManimCommunity 仓库发起一个 PR。

警告

请确保选择 ManimCommunity/manim 而不是 3b1b/manim 作为基础仓库！

选择你的派生项目中的分支作为源仓库——参见下面的截图。

请确保你遵循模板（这是首次打开“新建拉取请求”页面时显示的默认文本）。

你的更改在以下情况下有资格被合并：

没有合并冲突
我们的自动化流程中的测试通过
至少一位（对于更复杂的更改，两位）社区开发者批准了更改

你可以通过在本地执行 git pull upstream main 来检查当前 upstream/main 与你的分支之间是否存在合并冲突。如果这产生了任何合并冲突，你需要解决它们并将更新后的分支版本推送到你的仓库派生项目。

我们的自动化流程由一系列不同的测试组成，这些测试确保 Manim 仍按预期工作，并且你添加的代码符合我们的编码规范。

代码风格：我们使用 Black、isort 和 flake8 所要求的代码风格。GitHub 自动化流程会确保你的拉取请求中更改的（Python）文件也遵循此代码风格。如果此自动化流程步骤失败，请通过运行 black <file or directory> 和 isort <file or directory> 自动修复代码格式。要解决代码风格问题，请运行 flake8 <file or directory> 获取风格报告，然后手动修复 flake8 检测到的问题。
测试：自动化流程会在不同的操作系统（最新版本的 Ubuntu、macOS 和 Windows）上针对不同版本的 Python 运行 Manim 的测试套件。测试套件包括两种不同类型的测试：集成测试和文档测试。你可以在克隆的派生项目的根目录中分别通过执行 poetry run pytest 和 poetry run pytest --doctest-modules manim 在本地运行它们。
文档：我们还会构建一个与你的拉取请求对应的文档版本。请确保不要引入任何 Sphinx 错误，并查看已构建的 HTML 文件，以确认你添加的文档格式是否符合预期。你可以在 docs 目录中运行 make html 在本地构建文档。请确保你已在本地安装 Graphviz，以便构建继承图。有关更多信息，请参阅添加文档。

最后，如果自动化流程通过并且你对自己的更改感到满意：等待反馈并根据要求进行迭代修改。在此过程中，你可能会被要求以某种方式编辑或修改你的 PR。这不是对你工作的指责，而是一个强烈的信号，表明社区希望合并你的更改！一旦获得批准，你的更改就可能被合并！

其他有用指南¶

提交 PR 时，请明确提及是否包含破坏性更改。
提交 PR 时，请确保你提出的更改尽可能通用，并可供所有 Manim 用户利用。特别是，请省略任何特定于机器的配置或可能包含的任何个人信息。
如果你是维护者，请适当且频繁地标记问题和 PR。
打开新问题时，如果有相关旧问题，请在新问题中添加指向它们的链接（即使旧问题已关闭）。
提交代码审查时，强烈建议你遵守这些通用指南。
如果你发现陈旧或不相关的非活跃问题，请发表评论说“此问题应关闭”，社区开发者将会查看。
请尽可能保持问题、PR 和整体开发的整洁。

你可以在多个地方找到 docs 的示例：示例画廊、教程和参考类。

感谢你的贡献！