如何为 Incus 贡献代码

Incus 团队感谢您通过拉取请求、GitHub 仓库上的问题或论坛上的讨论或问题来为该项目做出贡献。

在为项目做出贡献之前，请查看以下指南。

行为准则

在贡献时，您必须遵守行为准则，该准则可在以下位置获得：https://github.com/lxc/incus/blob/main/CODE_OF_CONDUCT.md

拉取请求

对本项目的更改应作为拉取请求在 GitHub 上提出：https://github.com/lxc/incus

然后，建议的更改将在那里进行审查，并在批准后合并到主分支中。

提交结构

应将单独的提交用于

  • API 扩展（api: Add XYZ extension，包含 doc/api-extensions.md 和 internal/version/api.go）

  • 文档（doc: Update XYZ 用于 doc/ 中的文件）

  • API 结构（shared/api: Add XYZ 用于对 shared/api/ 的更改）

  • Go 客户端包（client: Add XYZ 用于对 client/ 的更改）

  • CLI（cmd/<command>: Change XYZ 用于对 cmd/ 的更改）

  • Incus 守护进程（incus/<package>: Add support for XYZ 用于对 incus/ 的更改）

  • 测试（tests: Add test for XYZ 用于对 tests/ 的更改）

相同的模式扩展到 Incus 代码树中的其他工具，并且根据复杂性，可以将事物拆分为更小的块。

在更新 CLI 工具 (cmd/) 中的字符串时，您可能需要一个提交来更新模板

make i18n
git commit -a -s -m "i18n: Update translation templates" po/

在更新 API (shared/api) 时，您可能需要一个提交来更新 swagger YAML

make update-api
git commit -s -m "doc/rest-api: Refresh swagger YAML" doc/rest-api.yaml

这种结构使贡献更容易被审查，并且极大地简化了将修复程序反向移植到稳定分支的过程。

开发者证书来源

为了更好地跟踪对本项目的贡献，我们使用 DCO 1.1 并对进入分支的所有更改使用“签署”程序。

签署是在提交说明末尾的一行简单文本，证明您编写了它或以其他方式有权将其作为开源贡献传递。

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

有效签署行的示例为

Signed-off-by: Random J Developer <random@developer.org>

使用已知的身份和有效的电子邮件地址。抱歉，不允许匿名贡献。

我们还要求每个提交都由其作者单独签署，即使是更大集合的一部分。您可能会发现 git commit -s 很有用。

为代码做出贡献

按照以下步骤设置您的开发环境，开始为 Incus 开发新功能。

从源代码安装 Incus

要构建依赖项，请按照从源代码安装 Incus中的说明进行操作。

将您的 fork 添加为远程

在设置好构建环境后，将您的 GitHub fork 添加为远程仓库

git remote add myfork git@github.com:<your_username>/incus.git
git remote update

然后切换到它

git checkout myfork/main

构建 Incus

最后，您应该能够在仓库内部运行 make 并构建您项目的 fork。

此时，您很可能希望在您的 fork 上为您的更改创建一个新的分支

git checkout -b [name_of_your_new_branch]
git push myfork [name_of_your_new_branch]

Incus 新贡献者重要说明

  • 持久化数据存储在 INCUS_DIR 目录中，该目录由 incus admin init 生成。 INCUS_DIR 默认为 /var/lib/incus。

  • 在开发过程中，您可能希望更改 Incus fork 的 INCUS_DIR 以避免版本冲突。

  • 从您的源代码编译的二进制文件默认情况下将生成在 $(go env GOPATH)/bin 目录中。

    • 在测试您的更改时，您需要显式调用这些二进制文件（而不是您可能已安装的全局 incusd）。

    • 您可以选择在您的 ~/.bashrc 中创建一个别名，以便更方便地使用适当的标志调用这些二进制文件。

  • 如果您有一个 systemd 服务配置为从先前安装的 Incus 运行 Incus 守护进程，您可能希望禁用它以避免版本冲突。

参与文档贡献

我们希望 Incus 尽可能易于使用和直观。因此，我们的目标是提供包含用户使用 Incus 所需信息的文档，涵盖所有常见用例，并解答典型问题。

您可以通过多种不同的方式参与文档贡献。感谢您的贡献！

典型的贡献方式包括

  • 为代码中您贡献的新功能或功能改进添加或更新文档。我们将审查文档更新并将其与您的代码合并。

  • 添加或更新文档，以阐明您在使用产品时遇到的任何疑问。此类贡献可以通过拉取请求或在论坛的 教程 部分发布帖子来完成。新的教程将被考虑纳入文档（通过链接或包含实际内容）。

  • 要请求修复文档，请在 GitHub 上提交文档问题。我们将评估问题并相应地更新文档。

  • 在 论坛 上发布问题或建议。我们将监控帖子，并在必要时相应地更新文档。

  • 在 IRC 上的 #lxc 频道中提问或提供建议。鉴于 IRC 的动态特性，我们无法保证对 IRC 帖子的回复或反应，但我们会监控该频道并尝试根据收到的反馈改进我们的文档。

文档框架

Incus 的文档使用 Sphinx 构建。

它使用带 MyST 扩展的 Markdown 编写。有关语法帮助和指南，请参阅 文档备忘单（源代码）。

在结构方面，文档使用 Diátaxis 方法。

构建文档

要构建文档，请从仓库的根目录运行 make doc。此命令将安装所需的工具并将输出呈现到 doc/html/ 目录中。要仅更新已更改文件的文档（无需重新安装工具），请运行 make doc-incremental。

在打开拉取请求之前，请确保文档构建没有警告（警告被视为错误）。要在本地预览文档，请运行 make doc-serve 并转到 http://localhost:8001 以查看渲染后的文档。

当您打开拉取请求时，会自动构建文档输出的预览。

自动文档检查

GitHub 对文档运行自动检查，以验证拼写、链接的有效性、Markdown 文件的正确格式以及包容性语言的使用。

您也可以（也应该！）使用以下命令在本地运行这些测试

  • 检查拼写：make doc-spellcheck

  • 检查链接的有效性：make doc-linkcheck

  • 检查 Markdown 格式：make doc-lint

  • 检查包容性语言：make doc-woke

要运行上述操作，您需要以下内容

  • Python 3.8 或更高版本

  • venv Python 包

  • 用于拼写检查的 aspell 工具

  • Markdown lint 工具 mdl

文档配置选项

注意

我们目前正在将配置选项的文档迁移到代码注释中。目前，并非所有配置选项都遵循此方法。

配置选项的文档是从 Go 代码中的注释中提取的。在代码中查找以 gendoc:generate 开头的注释。

当您添加或更改配置选项时，请确保为其包含所需的文档注释。

然后运行 make generate-config 以重新生成 doc/config_options.txt 文件。应检入更新后的文件。

文档包含来自 doc/config_options.txt 的部分，以显示一组配置选项。例如，要包含核心服务器选项

% Include content from [config_options.txt](config_options.txt)
```{include} config_options.txt
    :start-after: <!-- config group server-core start -->
    :end-before: <!-- config group server-core end -->
```

如果您向现有组添加配置选项，则无需对文档文件进行任何更新。新选项将自动被获取。只有在定义新组时，才需要向文档文件添加包含。