Go Task 中文文档

Appearance

贡献指南 ​

Task 的贡献非常受欢迎，但我们在提交 PR 之前要求您阅读本文档。

INFO

本文档适用于核心 Task 仓库 和 Visual Studio Code 的 Task。

开始之前 ​

  • 检查现有工作 - 是否存在现有的 PR？是否有讨论您想要实现的特性/更改的 issue？请确保在您的工作中考虑/解决这些讨论。
  • 向后兼容性 - 您的更改是否会破坏现有的 Taskfile？如果您的更改向后兼容，则更有可能被合并。您可以采取什么方法来维护这种兼容性？如果不能，请考虑先开启一个 issue，以便在您投入时间编写 PR 之前讨论 API 更改。
  • 实验 - 如果无法使您的更改向后兼容，则有一种程序可以将破坏性更改引入到次要版本中。我们将这些称为“实验”。如果您打算从事实验工作，请仔细阅读 实验工作流程 文档，并首先提交提案。

1. 设置 ​

  • Go - Task 是用 Go 编写的。我们始终支持最新的两个主要 Go 版本，因此请确保您的版本足够新。
  • Node.js - Node.js 用于托管 Task 的文档服务器，如果您想在本地运行此服务器，则需要它。如果您想为 Visual Studio Code 扩展贡献代码，也需要它。
  • Pnpm - Pnpm 是 Task 使用的 Node.js 包管理器。

2. 进行更改 ​

  • 代码风格 - 尽量保持现有的代码风格，在可能的情况下。Go 代码应由 golangci-lint 进行格式化和 lint 检查。它包装了 gofumpt 和 gci 格式化工具以及多个 linter。我们建议您查看 golangci-lint 文档，了解如何设置编辑器以自动格式化您的代码。任何 Markdown 或 TypeScript 文件都应由 Prettier 进行格式化和 lint 检查。此风格由我们的 CI 强制执行，以确保项目中风格一致。您可以使用 task lint 命令在本地 lint 代码，并使用 task lint:fix 命令尝试自动修复发现的问题。如果您的编辑器没有为您做好，您还可以使用 task fmt 命令自动格式化文件。
  • 文档 - 确保添加/更新任何相关的文档。请参阅下面的 更新文档 部分。
  • 测试 - 确保添加/更新任何相关的测试，并在提交 PR 之前确保所有测试通过。请参阅下面的 编写测试 部分。

运行您的更改 ​

要使用工作更改运行 Task，您可以使用 go run ./cmd/task。要针对 testdata 中的测试 Taskfile 运行 task 的开发构建，您可以使用 go run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>。

要运行 Visual Studio Code 的 Task，您可以在 VSCode 中打开项目并按 F5（或您设置的调试键绑定）。这将打开一个新 VSCode 窗口，扩展正在运行。以这种方式调试是推荐的，因为它允许您设置断点并逐步执行代码。否则，您可以运行 task package，这将生成一个 .vsix 文件，可用于手动安装扩展。

更新文档 ​

Task 使用 Vitepress 来托管文档服务器。此代码位于核心 Task 仓库中。您可以使用 task website（需要 nodejs 和 pnpm）在本地设置并运行它。所有内容均用 Markdown 编写，位于 website/src 目录中。所有 Markdown 文档应有 80 个字符的行宽限制（由 Prettier 强制执行）。

在进行更改时，请考虑是否需要更改 使用指南。本文档包含 Task 特性的描述和示例。如果您添加了一个新特性，请尝试找到合适的位置添加新部分。如果您正在更新现有特性，请确保文档和任何示例是最新的。确保任何示例遵循 Taskfile 风格指南。

如果您添加了一个新命令或标志，请确保将其添加到 CLI 参考。新字段也需要添加到 Schema 参考 和 JSON Schema 中。文档和模式中的字段描述应匹配。

编写测试 ​

Task 的大多数测试都保存在项目根目录的 task_test.go 文件中，您很可能也想在那里添加新的测试。这些测试中的大多数在 testdata 目录中有一个子目录，其中存储运行测试所需的任何 Taskfile/数据。

在进行更改时，请考虑是否需要新测试。这些测试应确保您添加的功能在未来继续工作。如果您更改了 Task 的行为，现有的测试也可能需要更新。

您也可以考虑为任何新添加的函数添加单元测试。单元测试应遵循 Go 约定，即位于与被测试代码相同包中的名为 *_test.go 的文件中。

3. 提交您的代码 ​

尽量编写有意义的提交消息，并避免在 PR 中有太多提交。大多数 PR 很可能只有一个提交（尽管对于更大的 PR，将其拆分为几个提交可能是合理的）。Git squash 和 rebase 是您的朋友！

如果您不确定如何格式化您的提交消息，请查看 Conventional Commits。此风格不是强制性的，但它是使您的提交消息更易读和一致的好方法。

4. 提交 PR ​

  • 描述您的更改 - 确保提供您更改的全面描述。
  • Issue/PR 链接 - 链接任何先前工作，例如相关的 issue 或 PR。请描述您的更改如何与此工作不同/扩展。
  • 示例 - 添加您认为有助于演示更改效果的任何示例或截图。
  • 草稿 PR - 如果您的更改不完整，但您想讨论它们，请将 PR 作为草稿打开并添加评论以开始讨论。使用评论而不是 PR 描述允许在保留任何讨论的同时稍后更新描述。

常见问题 ​

我想贡献，从哪里开始？

查看 Task 的 开放 issue 列表 或 Visual Studio Code 的 Task。我们有一个 good first issue 标签，用于更简单的 issue，这些 issue 适合首次贡献。

欢迎各种贡献，无论是拼写错误修复还是闪亮的新特性。您也可以通过为 issue 点赞/评论、帮助回答问题或贡献其他 社区项目 来贡献。

我卡住了，在哪里可以获得帮助？

如果您有问题，请随时在我们的 Discord 服务器 的 #help 论坛频道中询问，或在 GitHub 上开启一个 讨论。