Tribble

TL;DR Tribble是一个命令行工具，它从单个配置文件生成微型网站，以指导用户通过贡献开源项目。

问题

想象一下，你是一个新用户，想为一个大型的项目添加一个页面到他们的文档中。 但是，他们使用了一个自定义的文档系统，讽刺的是，这个系统本身没有文档，CONTRIBUTING.md 文件只是说克隆仓库并使用提供的构建脚本，但这些脚本本身也没有文档！通常，大多数用户这时就会放弃。有些人可能会在仓库中打开一个issue，或者在某个渠道中询问，然后可能会得到一些指导。但这并不帮助下一个用户，或者下下个用户。而且如果你不断地往CONTRIBUTING.md 文件里添加内容，它往往会变成一系列关于奇特的随机事实的集合，而不是一个有用的资源。这时候，Tribble就出现了。

作为维护者，我们希望专注于编写代码，而不是编写文档，当然更不会编写关于如何编写更多文档的文档！在大型的仓库中，有无数种人们可以贡献的方式，但传统的CONTRIBUTING.md 文件根本无法涵盖它们，而且你可能会花更多的时间帮助人们了解如何贡献，而不是真正解决问题，如果项目足够大。

作为用户，向大型项目贡献可能会让人感到害怕，我们想确保我们做的是正确的事情。但是，如果文档不完整，或者更糟糕的是不存在，那就非常困难！对于巨大的项目，很多高质量的贡献者可能会在早期阶段就因为不知道如何贡献而流失。

解决方案

如果每个项目都有一个覆盖所有贡献方式的庞大流程图，并且包含每个部分的独特之处，会怎么样？如果维护者只需编写一个配置文件就能表达所有这些信息，包含人们为贡献项目所需的所有信息，会怎么样？如果这个流程图是交互式的，有按钮和文本输入来引导用户完成贡献过程，会怎么样？如果这也适用于问题，引导新用户完成提供报告错误所需的所有信息，会怎么样？如果这个过程能自动为问题生成标签，有效地提供自动问题分类呢？

这就是 Tribble。

Tribble 是一个命令行工具，它接受一个用 YAML 编写的配置文件，并将其转换为一个使用 Perseus 构建的完整网站，该网站包含一个交互式流程图，用于指导用户完成贡献过程。在每一个阶段，可以积累 标签，这些标签可以自动添加到通过 Tribble 报告的 GitHub 问题中。它旨在简化编写和维护贡献文档的过程，指导用户提供维护者进行问题分类所需的信息，并自动执行基本分类（分配用户和添加标签）。

安装

Tribble 是一个完全自带的二进制文件，使用 Rust 构建，以实现性能和安全，您可以从发布页面或使用 Cargo（Rust 的包管理器）下载。

手动下载

如果您不使用 Rust，最简单的方法是从 发布页面下载适用于您的系统的最新二进制文件，然后将其放在您放置二进制文件的地方（例如 Linux 上的 /usr/local/bin）。

Tribble 自动为 Windows、MacOS、Linux 和 Linux musl（尤其是针对 Alpine Linux Docker 容器）生成二进制文件。如果您需要其他平台的二进制文件，您需要手动使用 Cargo 编译，您可以通过以下说明进行安装这里。然后按照使用 Cargo 安装 Tribble 的说明进行操作，您就设置好了！（此外，如果您认为我们应该为您的平台提供二进制文件，请随时 提出问题）。

使用 Cargo

如果您已安装 Cargo，只需运行以下命令即可设置好！

RUSTFLAGS=--cfg=web_sys_unstable_apis cargo install tribble

其他包管理器

将来，Tribble 将在更多的包管理器上分发，以便更容易安装。

使用方法

Tribble CLI 接收一个配置文件，它期望这个文件位于项目根目录，文件名为 tribble.yml。如果您需要使用其他名称，请随意，您可以通过传递参数来告诉 CLI，使用 -c <your-config-file-name-here>。无论您命名为什么，它都必须使用 YAML 格式编写。为了开始，请将以下内容放入目录中的 tribble.yml 文件中。

workflows:
  test:
    sections:
      Start:
        - "Hello, and welcome to the first stage of your contribution journey with Tribble!"
        - { text: "I want to report a bug", link: "Report Bug", tags: [ "C:bug" ] }
        - { text: "I want to suggest an enhancement", link: "Request Enhancement", tags: [ "C:enhancement" ] }
        - { text: "I'd like to add something to the docs", link: "endpoint:Documentation", tags: [ "C:docs" ] }
      Report Bug:
        - "Welcome to the section for reporting bugs!"
        - { id: "bug_description", label: "Describe the bug", type: "text" }
        - { id: "test_textarea", label: "Textarea", type: "multiline" }
        - { id: "test_datetime", label: "Datetime", type: "datetime-local" }
        - { id: "bool", label: "Boolean", type: "boolean" }
        - { text: "This bug occurs on the frontend", link: "endpoint:Bug", tags: [ "A:frontend" ] }
      Request Enhancement:
        - "Welcome to the section for suggesting enhancements!"
        - { id: "feature_area", label: "Which area of the system does your feature affect?", options: [ "Frontend", { text: "Backend", tags: [ "A:backend" ] } ], can_select_multiple: true }
        - { id: "test_select", label: "Which of the following best describes you?", options: [ "User", "Developer" ] }
        - { text: "Continue", link: "endpoint:Enhancement", tags: [] }
    index: Start
    endpoints:
      Bug:
        preamble: "Thank you very much for reporting this bug, we'll get on it right away!"
        text: "This report is reporting a bug. Description: ${bug_description}. Boolean: ${bool}"
        dest_text: "Report on GitHub"
        dest_url: "#"
      Enhancement:
        preamble: "Thanks for the request, we'll take a look!"
        text: "This report is requesting an enhancement to the ${feature_area}."
        dest_text: "Report on GitHub"
        dest_url: "#"
      Documentation: "You can contribute to the docs by doing foobar!"

文件准备好后，现在在同一目录下运行 tribble serve，这将立即（根据我们的测试，为 37 毫秒）为您生成一个应用程序的网站，您可以在 https://127.0.0.1:8080 上查看。如果您想更改主机的地址或端口号，可以带 --host 和 --port 标志运行该命令。

这就是 Tribble 的工作方式！您可以在 这里 查看完整的 API 文档（从 Rust 代码自动生成）。

国际化

我们刚才所做的一切都非常好，但大型项目往往需要使用多种语言的文档，那么Tribble是如何处理的呢？嗯，如果您在tribble.yml中创建一个包含此内容的Tribble文件，您就会看到了！

languages:
  en-US: en-US.yml

这定义了我们支持的语言以及它们的配置文件链接。然后，在en-US.yml中名为test的工作流程将在/workflow/en-US/test处可用。您可以为您的地区命名任何您想要的名称，但我们建议使用[language]-[REGION]方法（例如：en-US、en-GB、zh-CN、ru-RU）。有了这个，您的Tribble实例现在可以支持您想要的任何语言！

CLI命令

Tribble CLI仅支持五个命令，但它们可以为贡献者创建复杂且直观的用户体验。请注意，您可以使用顶级-c/--config标志更改配置文件的位置（例如：tribble -c test.yml serve）。

• build -- 构建您的工作流程（由tribble serve自动调用，所以除非您想调查底层文件，否则不需要这个命令）
• clean -- 清除因损坏而产生的Tribble元数据
• deploy -- 将您的工作流程构建为静态文件以进行部署，生成一个pkg/文件夹（可使用-o/--output进行更改）
• help -- 显示CLI的帮助页面，它将告诉您本节中的所有内容
• serve -- 在本地提供服务以进行开发，监视Tribble配置文件的变化（如果您添加了新的地区，则需要重新运行）

部署

一旦您构建了一些Tribble工作流程，并希望将它们部署到您的网站，请运行tribble deploy --path <serve-path>（其中<serve-path>是您将提供Tribble的相对路径的URL，例如：/tribble）以生成一个pkg/文件夹。这将包含您可以将它们部署到支持服务静态资产的任何托管提供商的静态文件。例如，在GitHub Pages上，只需将该文件夹添加到网站的根目录，并将其重命名为tribble，然后您就可以在https://<your-username>.github.io/<your-repo>/tribble/workflow/test访问test工作流程。生成的文件完全适用于生产环境，并且它们将使用Perseus构建一个性能极好的网站，它使用浏览器中的Rust来实现最佳性能。请注意，但您的流程只能在支持WebAssembly的浏览器中使用（基本上是除Internet Explorer以外的所有浏览器）。一般来说，可能为开源项目做出贡献的开发者将拥有现代浏览器。

如果您想在同一个地方托管多个项目的 Tribble 实例，不用担心，这正是工作流程的作用！您可以定义任意多个（只要它们在所有地区都相同），然后您可以使用一个 Tribble 实例为许多完全不同的项目（或者只为一个非常大的项目的不同部分）服务。

如果您访问已部署的 Tribble 实例并看到一个未样式化的网站（即占用整个屏幕的大量箭头），请确保在 tribble deploy 中 --path 设置正确。Tribble 使用此设置来确定其位置以及其 CSS 文件的位置，因此当此设置不正确时，它看起来没有样式。

与 GitHub 集成

Tribble 最强大的功能之一是它允许用户在通过工作流程时积累标签。更好的是，这些标签可以通过 Tribble 机器人 自动转换为 GitHub 上的标签！这样做的主要好处是问题可以完全自动分类，从而更快地响应问题并简化项目管理。

目前，Tribble 只支持与 GitHub 集成，但如果有人感兴趣，我们非常愿意考虑开发与其他平台集成的功能！

许可证

请参阅 LICENSE。