Tribble

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

问题

想象一下，你是一个新手用户，你想在项目的文档中添加一个页面。 但是，他们使用的是一个定制的文档系统，而这个系统讽刺性地没有文档。 CONTRIBUTING.md 文件只说克隆仓库并使用提供的构建脚本，但这些脚本也没有文档！通常，大多数用户现在就会放弃。有些人可能会在仓库中打开一个问题或在一些其他渠道中提问，然后他们可能会在这个过程中得到指导。但这并不能帮助下一个用户或他们之后的用户。如果你继续在 CONTRIBUTING.md 文件中添加内容，它往往会变成一系列关于怪癖的随机事实的集合，而不是一个有用的资源。这就是Tribble的用武之地。

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

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

解决方案

如果每个项目都有一个涵盖所有贡献方式的巨型流程图，并包含每个部分的特有信息，那会怎么样？如果维护者可以写一个包含所有必要信息的配置文件来指导人们如何贡献到他们的项目，那会怎么样？如果这个流程图是交互式的，有按钮和文本输入来引导用户完成贡献过程，又会怎么样？如果这也适用于问题，新手被引导提供所有必要的报告bug的信息，又会怎么样？如果这个过程能够为问题自动生成标签，从而有效地提供自动问题分类呢？

这就是 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。如果您需要命名其他名称，请随意命名，并通过传递-c <您的-配置-文件-名称-在这里>来通知CLI。无论您如何命名，它都必须以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 实例现在可以支持您想要支持的所有语言！