Help us learn about your current experience with the documentation. Take the survey.

贡献内部事件 CLI

CLI 的优先级

  1. 与 instrumentation 能力保持功能对等，因为 CLI 是所有 instrumentation 任务的主要入口点
  2. 性能和手动测试是最高优先级，因为 CLI 主要负责为用户提供清晰简洁的用户体验
  3. 如果用户选择不使用 CLI，danger/specs/pipelines 仍然能确保定义有效性/数据完整性/功能等

UX 风格指南与原则

何时使用生成器

内部事件生成器应该：

  • 成为与指标测量相关的任何工程任务的一站式解决方案

内部事件生成器 不应该：

  • 成为必需品；用户应该能够手动完成相同的任务

我们对用户的期望

内部事件生成器应该：

  • 保护用户免犯错误
  • 在任何时间点告知用户完成目标还需要完成哪些任务
  • 基于用户在屏幕上看到的信息，告知选择特定选项或输入文本的后果

内部事件生成器 不应该：

  • 要求用户在运行生成器前了解任何关于 instrumentation 的知识
  • 要求用户在需要特定上下文来完成给定任务时切换屏幕
  • 在没有提供替代路径的情况下阻止用户继续操作

我们对开发环境的期望

内部事件生成器应该：

  • 比手动执行相同任务更快
  • 如果被强制退出，应保持用户环境处于干净且有效的状态

内部事件生成器 不应该：

  • 在存在无效的用户生成内容时崩溃
  • 要求 Rails 正在运行
  • 要求使用功能正常的 GDK

与用户建立期望

内部事件生成器应该：

  • 显示进度条，并在每个屏幕顶部详细说明所需步骤
  • 有基于结果的入口点来定义每个流程
  • 使用轻松热情的语调

向用户传达信息

内部事件生成器应该：

  • 为所有内容提供文本标签和解释
  • 用户退出 CLI 时始终打印 InternalEventsCli::Text::FEEDBACK_NOTICE
  • 使用示例来说明结果

内部事件生成器 不应该：

  • 仅使用颜色和格式作为传达信息或上下文的机制

从用户收集信息

内部事件生成器应该：

  • 优先使用选择菜单而不是纯文本输入
  • 在可能的情况下自动填充默认值，或使用之前的选择来推断信息
  • 将最常见的用例作为第一个/最容易的/默认选项
  • 始终允许任何有效选项；CLI 永远不应该假设最常见的用例总是被使用

内部事件生成器 不应该：

  • 要求用户多次输入相同的信息
  • 在使用 CLI 全屏时，让交互"超出屏幕折叠线"（尽可能避免）

设计技巧

  • 参考 scripts/internal_events/cli/helpers/formatting.rb 来格式化不同类型的信息和输入。
  • 添加或删除内容可能会影响流程的运行效果。始终考虑更广泛的上下文，不要害怕进行其他修改来改善 UX。
  • 不要使用带依赖关系和验证的多选菜单，考虑使用列出每个允许组合的单选菜单。这可能并不总是有效，但交互更快，并且让用户更清楚选择的结果。
  • 添加到现有流程时，尽可能匹配现有屏幕的格式和结构。思考每段文本的功能，然后 a) 按功能分组相关文本，或 b) 按主题分组相关文本，并对每个主题使用相同的功能顺序。

开发实践

  • 功能文档：与 CLI 更新同步发布文档更新
    • 如果 CLI 是我们推荐的所有 instrumentation 的入口点，它必须始终保持功能完整。它不应该 落后于文档或我们向其他团队宣布的功能。
  • CLI 文档：尽可能依赖 CLI 代码的内联或同地文档
    • 我们在处理 CLI 时越有可能发现上下文/解释，我们就越有可能 a) 减少未使用/重复代码的可能性，b) 提高代码的可导航性和重新熟悉的速度。
  • 测试：像对待前端应用程序一样对待测试
    • 自动化测试应该主要是面向 UX 的 E2E 测试，辅以边缘情况测试和按需进行的单元测试。
    • 在绝对需要防止回归的地方应用单元测试。
  • 验证：添加功能支持时始终直接运行 CLI
    • 我们不能只依赖自动化测试。如果我们的目标是优秀的用户体验，那么我们作为用户是确保我们合并的所有内容都服务于该目标的关键工具。如果手动测试很繁琐和烦人，那么使用起来可能也很繁琐和烦人。

FAQ

问：为什么 InternalEventsCli::Event 和 InternalEventsCli::Metric 不使用 Gitlab::Tracking::EventDefinition 和 Gitlab::Usage::MetricDefinition？

答：使用 EventDefinition 和 MetricDefinition 类需要运行 GDK 并加载 rails 应用。CLI 的性能对其可用性至关重要，因此单独的类值得拥有快速的启动时间。理想情况下，这将及时重构，以便相同的类可以同时用于 CLI 和 rails 应用。目前，rails 应用和 CLI 共享定义的 json-schemas 作为单一事实来源。