7.1 KiB
| slug | sidebar_position |
|---|---|
| /contributing/ | 11 |
贡献
非常欢迎对 Task 的贡献，但我们要求您在提交 PR 之前阅读本文档。
:::note
本文档适用于 Task 核心存储库 和 Task for Visual Studio Code。
:::
开始之前
- 检查已有工作 - 是否已经存在 PR？ 是否存在 Issue 正在讨论您要进行的功能/更改？ 请确保你的工作中确实考虑了这些相关的讨论内容。
- 向后兼容 - 你的变更是否破坏了已经存在的 Taskfile？ 向后兼容的变更会更容易被合并进去。 您是否可以采取一种方法来保持这种兼容性？ 如果没有，请考虑先提出一个 Issue，以便在您投入时间进行 PR 之前讨论 API 的更改。
- Experiments - If there is no way to make your change backward compatible then there is a procedure to introduce breaking changes into minor versions. We call these "[experiments][experiments]". If you're intending to work on an experiment, then please read the [experiments workflow][experiments-workflow] document carefully and submit a proposal first.
1. 设置
- Go - Task 使用 Go 编写。 我们始终支持最新的两个主要 Go 版本，因此请确保您的版本足够新。
- Node.js - Node.js 用于托管 Task 的文档服务器，如果您想在本地运行此服务器，则需要它。 如果您想为 Visual Studio Code 扩展做贡献，也需要它。
- Yarn - Yarn 是 Task 使用的 Node.js 包管理器。
2. 进行变更
- 代码风格 - 尽量保持现有的代码风格。 Go 代码应该由
gofumpt格式化并使用golangci-lint进行检查。 任何 Markdown 或 TypeScript 文件都应该由 Prettier 格式化和检查。 这种风格由我们的 CI 强制执行，以确保我们在整个项目中拥有一致的风格。 您可以使用task lint命令在本地检查代码，并使用task lint:fix命令自动修复发现的任何问题。 - 文档 - 确保添加/更新了相关文档。 请参阅下面的 更新文档 部分。
- 测试 - 确保添加/更新了相关测试，并且在提交 PR 前已通过所有测试。 请参阅下面的 编写测试 部分。
运行您的变更
要运行带有工作变更的任务，您可以使用 go run ./cmd/task。 要针对 testdata 中的测试任务文件运行任务的开发构建，您可以使用 go run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>。
要运行 Task for Visual Studio Code，您可以在 VSCode 中打开项目并按 F5（或任何您设置绑定的调试键）。 这将打开一个新的 VSCode 窗口，扩展正在运行。 建议以这种方式进行调试，因为它允许您设置断点并单步执行代码。 或者，您可以运行 task package，这将生成一个可用于手动安装扩展的 .vsix 文件。
更新文档
Task 使用 Docusaurus 来托管文档服务器。 此代码位于 Task 核心存储库中。 这可以通过使用 task docs（需要 nodejs 和 yarn）在本地设置和运行。 所有内容均使用 Markdown 编写，位于 docs/docs 目录中。 所有 Markdown 文档都应有 80 个字符的换行限制（由 Prettier 强制执行）。
When making a change, consider whether a change to the Usage Guide is necessary. This document contains descriptions and examples of how to use Task features. If you're adding a new feature, try to find an appropriate place to add a new section. If you're updating an existing feature, ensure that the documentation and any examples are up-to-date. Ensure that any examples follow the Taskfile Styleguide.
If you added a new field, command or flag, ensure that you add it to the API Reference. 还需要将新字段添加到 JSON Schema 中。 API 参考和 schema 中的字段描述应该匹配。
编写测试
许多 Task 的测试都保存在项目根目录下的 task_test.go 文件中，这也是您最有可能想要添加新测试的地方。 大多数这些测试在 testdata 目录中也有一个子目录，其中存储了运行测试所需的任何 Taskfiles/数据。
进行更改时，请考虑是否需要添加新的测试。 这些测试应确保您添加的功能在未来持续工作。 如果您更改了 Task 的行为，则现有测试也可能需要更新。
您还可以考虑为您添加的任何新功能添加单元测试。 单元测试应遵循 Go 约定，即位于与被测试代码相同的包中名为 *_test.go 的文件中。
3. 提交代码
尝试编写有意义的提交消息并避免在 PR 上有太多提交。 大多数 PR 应该有一个单一的提交（尽管对于更大的 PR 将它分成几个可能是合理的）。 Git squash(并和) 和 rebase(变基) 是你的好伙伴!
如果您不确定如何格式化提交消息，请查看 约定式提交。 这种风格不是强制的，但它是使您的提交消息更具可读性和一致性的好方法。
4. 提交 PR
- 描述变更 - 确保您提供对更改的全面描述。
- Issue/PR 链接 - 链接到之前相关的 Issue 或 PR。 请描述当前工作与之前的不同之处。
- 示例 - 添加您认为有助于展示更改效果的任何示例或屏幕截图。
- PR 草案 - 如果变更还未完成，但您想讨论它们，请将 PR 作为草稿打开并添加评论以开始讨论。 使用评论而不是 PR 描述允许稍后更新描述，同时保留讨论。
常见问题
我想贡献，我从哪里开始？
查看 Task 或 Task for Visual Studio Code 的未解决问题列表。 我们有一个 good first issue 标签，用于更简单的问题，非常适合首次贡献。
欢迎各种贡献，无论是拼写错误修复还是很小的新功能。 You can also contribute by upvoting/commenting on issues, helping to answer questions or contributing to other community projects.
我被困住了，我在哪里可以获得帮助？
如果您有任何疑问，请随时在我们的 Discord 服务器 上的 #help 论坛频道中提问，或在 GitHub 上打开 讨论。