贡献

SpeechBrain 的禅意

SpeechBrain 用于研究学术商业非商业目的,因此代码应该

  • 简单:直接明了,即使是学生、学者和非专业程序员也能轻松理解。复杂的代码,如果必须存在,应尤其详细解释。

  • 可读:避免抽象命名。链接到资源和参考文献,以帮助理解复杂主题或实现。代码风格和格式会自动强制执行。

  • 高效:并非所有都必须快,但对于应该快的,进行性能分析和优化。操作批次。优先使用张量操作而非大量 Python 构造。避免 CPU/GPU 同步。

  • 模块化:应该易于使用工具包中的任何功能。在有帮助时拆分函数/类。按逻辑分组功能。避免不必要的耦合。

  • 文档齐全:文档应完整,易于导航和发现。考虑编写教程

在 GitHub 上创建 Pull Request

  1. 我们使用 git 和 GitHub。

  2. 在你的 GitHub 账户下 fork speechbrain 仓库 (https://github.com/speechbrain/speechbrain)。(这会在你的账户下创建一个 SpeechBrain 的副本,GitHub 知道它的来源,我们通常称之为“上游”。)

  3. 克隆你自己的 speechbrain 仓库。 git clone https://github.com/ <your-account> /speechbrain (这会将 git 仓库下载到你的机器上,git 知道它的来源,并将其称为“origin”。)

  4. 为你开发的每个特定功能创建一个分支。 git checkout -b your-branch-name

  5. 进行 + 提交更改。 git add files-you-changed ... git commit -m "Short message about what you did"

  6. 将分支推送到你的 GitHub 仓库。 git push -u origin your-branch-name (这会将你的分支上传到你的 GitHub 仓库,并设置上游跟踪引用,以便将来的 git pushgit pull 命令会自动知道要同步的远程分支。)

  7. 导航到 GitHub,并从你的分支向speechbrain/speechbrain上游仓库的“develop”分支创建 Pull Request。

  8. Pull Request (PR) 会显示在上游仓库中。在那里讨论你的贡献。如果你向你的 GitHub 仓库(你的分支)推送更多更改,这些更改会添加到 PR 中。

  9. 当评审者认为代码提升了仓库质量时,他们可以合并。

请注意,创建 PR 时将运行 CI 测试。如果你想确保你的代码不会未能通过这些测试,我们已经设置了 pre-commit 钩子,你可以安装它们。参见 pre-commit 部分。

这些钩子会在你提交和推送代码时自动检查代码。

重要代码规范

我们支持特定范围的 Python 版本,这些版本通过 CI 进行测试。

格式化与 Linting

使用 pre-commit run -a 运行格式化和 Linting,底层使用 blackflake8 等工具(参见 .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 中,我们计划提供不同层次的文档

  • Docstrings:仓库中的每个类/函数都应该有一个头部,正确描述其功能、输入和输出。提供一个示例来展示如何将其用作独立函数也非常重要。我们使用 Numpy 风格的 Docstrings。一致的 Docstring 风格支持自动 API 文档。另请注意自动运行的 Doctests(参见此处)。

  • 注释:我们鼓励开发者编写自说明代码,并在实现令人惊讶(对 Python 熟悉者而言)以及实现算法需要澄清的地方使用适当的注释。

  • 网站文档。在 SpeechBrain 网站上,你可以找到工具包当前实现的每个功能的详细文档。

  • 教程:教程是让你通过交互式代码和解释熟悉 SpeechBrain 的好方法。

延伸阅读

内部贡献者