为 ansible-pylibssh 做贡献

注意

ansible-pylibssh 项目仅为了允许 Ansible 连接插件通过在 Python 中导入来使用 libssh SSH 实现而存在。目前，我们不接受任何与该目标无关的贡献或功能请求。

但如果你想贡献错误修复或发送拉取请求来改进我们的 CI、测试和打包，我们将很乐意审核。

为了做出贡献，你需要

  1. Fork 仓库。

  2. 创建一个分支，将你的更改推送到该分支。别忘了 包含变更日志的新闻文件.

  3. 将其作为 PR 发送给我们。

  4. 迭代你的 PR，包含请求的改进并参与讨论。

先决条件

  1. 拥有 libssh.

  2. 使用 tox 构建 C 扩展、文档并运行测试。

  3. 在发送 PR 之前，确保 linter 通过

    $ tox -e lint

另请参阅

测试指南

在本地运行测试套件

贡献文档

我们使用 Sphinx 生成我们的文档网站。你可以通过执行以下命令在本地触发该过程

$ tox -e build-docs

它也与 Read The Docs 集成，后者会构建并发布主分支上的每个提交，并为每个拉取请求生成实时文档预览。

Sphinx 文档的来源使用 reStructuredText 作为事实上的标准。但为了使文档贡献对初学者更友好，我们集成了 MyST 解析器，允许我们也接受用 Markdown 的扩展版本编写的新的文档，该版本支持使用 Sphinx 指令和角色。 阅读文档 以了解更多有关如何使用它的信息。

在你的 PR 中添加更改说明

维护软件更新到新版本对最终用户的影响的新闻日志非常重要。这就是为什么我们根据 Towncrier 的理念 强制在拉取请求中收集更改片段文件。

其理念是，当有人进行更改时，他们必须记录会影响最终用户的部分，仅包括对他们有用的信息。然后，当维护者发布新版本时，他们将自动使用这些记录为相应的版本编写变更日志。重要的是要理解，包含不必要的低级实现相关细节会产生噪音，这些噪音在大多数情况下对最终用户并不特别有用。因此，此类细节应记录在 Git 历史记录中，而不是变更日志中。

好的！那么如何添加新闻片段呢？

要提交有关你的 PR 的更改说明，请在 docs/changelog-fragments/ 文件夹中添加一个文本文件。它应该包含一个说明，解释应用此 PR 将如何改变最终用户与项目交互的方式。通常一句话就足够了，但请随意添加你认为对用户理解其含义必要的任何细节。

使用过去时编写片段中的文本，因为与其他片段组合在一起时，它将成为“新闻摘要”的一部分，告诉读者自上一个版本以来，库的特定版本中发生了哪些变化。你也可以使用reStructuredText 语法来突出显示代码（内联或块）、链接文档的部分或外部站点。但是，你不需要在此处引用问题或 PR 编号，因为towncrier 在渲染新闻文件时会自动添加对所有受影响问题的引用。如果你想签署你的更改，请随意在末尾添加 -- by :user:`github-username`（将 github-username 替换为你自己的用户名！）。

最后，按照 Towncrier 理解的约定命名你的文件：它应该以问题或 PR 的编号开头，后面跟着一个点，然后添加一个补丁类型，比如 feature、doc、contrib 等，最后添加 .rst 作为后缀。如果你需要添加多个片段，你可以在类型和后缀之间添加一个可选的序列号（用另一个点分隔）。

通常，名称将遵循 <pr_number>.<category>.rst 模式，其中类别为

  • bugfix: 对我们认为是不正确的、不期望的行为的错误修复，该行为已在发布中得到纠正，以符合预先商定的预期。

  • feature: 新的行为、公共 API。这类东西。

  • deprecation: 声明未来 API 移除和行为变更。

  • breaking: 当公共内容以破坏性的方式被移除时。可能在早期版本中被弃用。

  • doc: 对文档结构或构建过程的显著更新。

  • packaging: 针对下游的关于不明显副作用和工具的说明。测试调用注意事项和运行时假设的更改。

  • contrib: 影响贡献者体验的内容。例如，运行测试、构建文档、设置开发环境。

  • misc: 很难归入上述任何类别的更改。

一个拉取请求可能包含多个这些组件，例如，代码更改可能会引入一项新功能，该功能会弃用旧功能，在这种情况下，应添加两个片段。没有必要为伴随相关代码更改的文档更改单独创建文档片段。

用于向你的拉取请求添加变更日志条目的示例

文件 docs/changelog-fragments/112.doc.rst（可以符号链接到 docs/changelog-fragments/112.contrib.rst 以便它显示在多个变更日志部分中）

Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz`.

This change allows the contributors to be credited for their submitted
patches in a more prominent manner.

文件 docs/changelog-fragments/105.feature.rst

Added the support for keyboard-authentication method -- by :user:`Qalthos`.

文件 docs/changelog-fragments/57.bugfix.rst

Fixed flaky SEGFAULTs in ``pylibsshext.channel.Channel.exec_command()``
calls -- by :user:`ganeshrn`.

提示

请参阅 pyproject.toml 以查看所有可用类别 (tool.towncrier.type)。