撰写优秀的问题

所有出色的项目都是根据用户反馈建立的。Blockly 使用 GitHub 问题来跟踪反馈。本页详细介绍了如何编写便于开发者阅读和回复的问题，以便更好地解决您的 bug 报告/功能请求！

准备工作

有问题要问？

我们很乐意倾听你的问题！不过，GitHub 问题并不是很好的媒介。如果您有任何疑问，请访问我们的开发者论坛。如果您在该平台上提出问题，您更有可能得到及时、全面的回复，因为其中有很多开发者一直在使用 Blockly ！

检查重复内容

在编写任何类型的问题之前，最好先查看是否已存在匹配的问题。如果是这样，您就不必自己编写代码了！因此，在开始撰写之前，请先搜索一些重复的内容或相关问题。

如果您发现了匹配问题，请对它表示“我喜欢”或发表评论，详细说明您的想法。这对于 bug 报告和功能请求尤为重要。如果开发者发现某个问题获得了大量关注，便更有可能予以解决！

报告 bug

你觉得自己发现了错误？太好了！我们乐于收到 bug 报告，因为我们希望该项目尽可能保持稳定。您可以遵循以下步骤，帮助您修复 bug。

  1. 检查重复内容
  2. 收集证据
  3. 找到问题
  4. 固化您的复制
  5. 推荐原因
  6. 撰写您的问题！

收集证据

一般来说，错误信息越多越好。以下是您可能需要提供的一些信息：

  • 如果 bug 会导致视觉问题，屏幕截图或 GIF 会非常有用。
  • 如果 bug 仅影响某些类型的块或工作区配置，则示例代码非常有用。
  • 如果您无法在自己的特定环境之外重现错误，托管网站会是您的理想选择。

找到问题

从核心库、插件、示例到 Codelab 中，我们存储了大量 Blockly 代码。请告诉我们问题的确切位置，以帮助我们解决问题。

如果是核心问题，请选择哪个组件？例如，工具箱、缩放控件或库块存在问题。请尽可能具体。

如果问题出在 blockly-samples 中，请确定其所在的插件、Codelab 或示例。如果您在多个位置发现相同的错误，也请告知我们。

强化复制

bug 只有在可重现的情况下才能修复，因此在提交问题之前，请确保您有发布 bug 的可靠方法。

您最终应获得一个带编号的步骤列表，告诉开发者如何重现 bug。例如：

  1. 打开 X Codelab。
  2. 转到 Y 页面。
  3. 运行 Z 示例代码。
  4. 观察不良行为，看起来像 W。

如果您的问题在 Blockly 核心中，请尝试在playground中重现该问题。

推荐原因

如果您认为自己知道出现错误的原因，也请附上该信息。同样，请尽可能具体地说明。

撰写您的问题！

是时候撰写错误报告了。选择您的代码库：

请务必填写问题模板的所有部分，包括此处未详述的部分。

感谢您有兴趣报告 bug，祝您在撰写问题时一切顺利！

后续步骤

  • 系统会自动为您的 bug 报告添加标记以进行分类。
  • Blockly 团队的待命成员将进行查看，并可能会提出澄清性问题。开发者还会添加标签，以便我们整理 bug。
  • 问题可能会被标记为“需要帮助”，然后您可以声明该问题并开始解决。
  • 相应问题可能会分配给 Blockly 团队的成员进行修复。
  • 问题可能会用季度里程碑标记，以表明何时完成。
  • 该问题可能会被置于 Icebox 里程碑中，这意味着我们打算在可预见的未来对其进行处理。
    • 低频问题或采用已知解决方法的 bug 时可能会发生这种情况。
    • 您仍然可以处理 Iceboxed 问题。
  • 该问题可能会被放入“Bug Bash 积压”里程碑事件中，这意味着问题不紧急，但我们仍希望解决问题。
    • 每个季度结束时，团队都会花几周的时间来处理从 Bug Bash 积压任务里程碑中提取的 bug。
  • 如果需要，可以将问题从 Blockly 核心转移到块采样（或相反方向）。
  • 此问题可能已关闭。

功能请求

你有没有什么需要改进的地方，让 Blockly 变得更好？您对插件、示例或 Codelab 有想法吗？也许已经有你喜欢的动画，并且想出一种方法进行改进如果是，那您就来对地方了！以下步骤可帮助您创建出色的功能请求并获得响应。

  1. 检查重复内容
  2. 查看要求
  3. 收集您的想法
  4. 编写功能请求！

查看相关要求

我们非常希望允许每一个想法都加入到这个仓库中！可惜的是，我们只是人类，因此我们制定了一些准则来说明我们会处理的请求类型。

以下是各个不同类别项目的指南：

  • Blockly Core
  • 插件
  • 示例：展示如何仅使用一两个 Blockly 功能。
  • Codelab：展示如何完成一项任务或实现单一行为。

但这些并不是硬性规定。它们只是让您先了解我们的预期，然后再决定是否要花时间构建功能请求。

如果您不确定某些内容是否合适，请尝试在我们的开发者论坛上发帖。请记住，即使您的想法未被接受，我们也欢迎您将其构建为第三方插件或教程！

收集您的想法

在继续并提交您的想法之前，您不需要用五彩纸屑和图表来 100% 地充实您的想法，但是您应该清楚自己要寻找什么。在开始写作之前，请思考以下问题：

  • 为什么我需要此功能？
  • 此功能解决了问题吗？
  • 此功能的目标受众群体是谁？
  • 为什么此功能为他们服务？
  • 可以采用哪些替代方法来实现相同的目标？

弄清楚这些信息后，您就能提出好功能请求了！

编写功能请求！

现在，您可以编写功能请求了。选择您的代码库：

请务必填写问题模板的所有部分，包括此处未详述的部分。

感谢您有意提交功能请求，祝您撰写问题愉快！

后续步骤

  • 系统会自动为您的功能请求添加标记，以便进行分类。
  • Blockly 团队的待命成员将进行查看，并可能会提出澄清性问题。开发者还会添加标签，以便我们整理 bug。
  • 该功能可能会被标记为“需要帮助”，在这种情况下，您可以认领它并开始改进。
  • 该功能可能会分配给 Blockly 团队的成员进行实现。
  • 如果需要，可以将功能请求从 Blockly 核心移至块采样（或相反方向）。
  • 功能请求可能会被关闭，在这种情况下，您仍然可以选择作为第三方插件来实现该功能。