Manim 开发流程¶

对于首次贡献者¶

安装 git:

有关说明，请参见 https://git-scm.com/。
分叉项目：

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

警告

不要克隆ManimCommunity仓库。你必须克隆你自己的fork。
更改目录以进入项目文件夹：
```
cd manim
```

添加上游仓库，ManimCommunity：

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

现在，git remote -v 应该显示两个名为的远程仓库：
- origin，你的分叉仓库
- upstream ManimCommunity 仓库
安装Manim：
- 按照我们的安装说明中的步骤安装Manim的依赖项，主要是ffmpeg和LaTeX。
- 我们推荐使用Poetry来管理您的Manim开发者安装。Poetry是一个用于Python依赖管理和打包的工具。它允许您声明项目所依赖的库，并为您管理（安装/更新）这些库。此外，Poetry还提供了一个简单的界面来管理虚拟环境。
  
  如果你选择使用Poetry，请按照Poetry的安装指南在你的系统上安装它，然后从你克隆的仓库中运行poetry install。Poetry随后会安装Manim，并创建并进入一个虚拟环境。你可以随时通过运行poetry shell重新进入该环境。
- 如果你想安装定义在[tool.poetry.extras]部分的额外依赖项，可以通过传递-E标志来实现，例如poetry install -E jupyterlab -E gui。
- 如果你决定不使用Poetry，你可以通过运行python3 -m pip install .来通过pip安装Manim。请注意，由于我们的开发基础设施基于Poetry，我们目前不支持通过pip进行可编辑安装，因此每次更改源代码后都需要重新运行此命令。
注意

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

你现在已经准备好开始使用Manim了！

开发您的贡献¶

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

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

提示

在编写提交信息时，强烈建议您遵循这些指南。
添加新的或更新现有的测试。

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

更新您更改的任何函数或类的文档字符串（三重引号中的文本），并将其与您添加的任何新函数一起包含。有关我们更喜欢如何记录代码的更多信息，请参阅文档指南。文档字符串的内容将呈现在参考手册中。

提示

使用manim directive for Sphinx将示例添加到文档中！

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

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

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

注意

你不需要完成所有内容（代码/文档/测试）才能开启一个拉取请求（PR）。如果PR仍在开发中，请将其标记为草稿。社区开发者仍然可以审查更改，讨论尚未实施的更改，并提供建议；然而，你的PR越完整，它被合并的速度就越快。

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

为了让ManimCommunity开发团队了解您的更改，您可以从您的分支向ManimCommunity仓库提交一个PR。

警告

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

从你的分支中选择作为头部仓库的分支 - 参见下面的截图。

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

如果满足以下条件，您的更改将有资格被合并：

没有合并冲突
我们流水线中的测试通过了
至少一名（对于更复杂的更改需要两名）社区开发者批准更改

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

我们的流水线由一系列不同的测试组成，确保Manim仍然按预期工作，并且您添加的代码遵循我们的编码规范。

代码风格：我们使用由Black、isort和flake8强制的代码风格。GitHub流水线确保您的拉取请求中更改的（Python）文件也遵循此代码风格。如果流水线的此步骤失败，请通过运行black <文件或目录>和isort <文件或目录>自动修复代码格式。要修复代码风格问题，请运行flake8 <文件或目录>以获取风格报告，然后手动修复由flake8检测到的问题。
测试: 该管道在不同的操作系统（最新版本的Ubuntu、macOS和Windows）上为不同版本的Python运行Manim的测试套件。测试套件由两种不同的测试组成：集成测试和文档测试。你可以通过在克隆的fork的根目录下分别执行poetry run pytest和poetry run pytest --doctest-modules manim来在本地运行它们。
文档: 我们还会构建与您的拉取请求相对应的文档版本。确保不要引入任何Sphinx错误，并查看构建的HTML文件，以确保您添加的文档格式符合预期。您可以通过在docs目录中运行make html来本地构建文档。确保您本地安装了Graphviz以构建继承图。有关更多信息，请参阅添加文档。

最后，如果管道通过并且您对您的更改感到满意：等待反馈并迭代任何请求的更改。在此过程中，您可能会被要求以某种方式编辑或修改您的PR。这不是对您工作的指责，而是社区希望合并您的更改的强烈信号！一旦获得批准，您的更改可能会被合并！

Manim 开发流程¶

对于首次贡献者¶

开发您的贡献¶

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

更多有用的指南¶