贡献
SpeechBrain 的禅意
SpeechBrain 用于研究、学术、商业、非商业目的,因此代码应该
在 GitHub 上创建 Pull Request
我们使用 git 和 GitHub。
在你的 GitHub 账户下 fork speechbrain 仓库 (https://github.com/speechbrain/speechbrain)。(这会在你的账户下创建一个 SpeechBrain 的副本,GitHub 知道它的来源,我们通常称之为“上游”。)
克隆你自己的 speechbrain 仓库。
git clone https://github.com/ <your-account> /speechbrain
(这会将 git 仓库下载到你的机器上,git 知道它的来源,并将其称为“origin”。)为你开发的每个特定功能创建一个分支。
git checkout -b your-branch-name
进行 + 提交更改。
git add files-you-changed ...
git commit -m "Short message about what you did"
将分支推送到你的 GitHub 仓库。
git push -u origin your-branch-name
(这会将你的分支上传到你的 GitHub 仓库,并设置上游跟踪引用,以便将来的git push
或git pull
命令会自动知道要同步的远程分支。)导航到 GitHub,并从你的分支向speechbrain/speechbrain上游仓库的“develop”分支创建 Pull Request。
Pull Request (PR) 会显示在上游仓库中。在那里讨论你的贡献。如果你向你的 GitHub 仓库(你的分支)推送更多更改,这些更改会添加到 PR 中。
当评审者认为代码提升了仓库质量时,他们可以合并。
请注意,创建 PR 时将运行 CI 测试。如果你想确保你的代码不会未能通过这些测试,我们已经设置了 pre-commit 钩子,你可以安装它们。参见 pre-commit 部分。
这些钩子会在你提交和推送代码时自动检查代码。
重要代码规范
我们支持特定范围的 Python 版本,这些版本通过 CI 进行测试。
格式化与 Linting
使用 pre-commit run -a
运行格式化和 Linting,底层使用 black
和 flake8
等工具(参见 .pre-commit-config.yaml
)。有些检查会自动修复你的代码,有些可能需要你手动干预。
这些检查在 CI 上运行并强制执行。
运行测试
我们使用 pytest。使用 pytest tests
运行单元测试
此外,我们有可运行的 Doctests,它们主要用作文档化代码的示例。使用 pytest --doctest-modules <file-or-directory>
运行 Doctests
这些检查在 CI 上运行并强制执行。
添加依赖项
一般来说,我们努力保持尽可能少的依赖项。但是,我们将根据具体情况讨论新的依赖项。我们重视保持工具包的轻量化,以便通过 pip 轻松安装,并减少在面对冲突依赖项时维护工具所需的工作。
如果某个依赖项仅用于特定 recipe,我们建议使用额外工具模式:不要将该依赖项添加到通用 requirements 中,而是将其添加到该特定 recipe 的 extra-requirements.txt
文件中。
最后,如果你想向 SpeechBrain 核心工具添加内容,但某个依赖项无法添加到完整的工具包依赖项列表中,你可以将该工具添加到 speechbrain/integrations
文件夹中,这需要更多的测试,并且仅在每次发布前验证其功能,而不是在每次 CI 运行时都验证。
重要文档规范
在 SpeechBrain 中,我们计划提供不同层次的文档