tribble.yml

workflows:
  perseus:
    title: "Perseus Contributing Documentation"
    sections:
      Start:
        - "Welcome to the contributing website for Perseus! This tool will guide you through helping to contribute to Perseus by walking you through an interactive flowchart. To start off, please select one of the following."
        - "If you go through this system and you can't find what you're looking for, please come back to this page and select *Other*."
        - "*Please note that this system is still in development, and will likely be incomplete. If things are unclear here, please feel free to open an issue directly through GitHub.*"
        - { text: "I want to report a bug in Perseus", link: "Bug Type", tags: [ "tribble-reported", "C-bug" ] }
        - { text: "I want to request a feature for Perseus", link: "Enhancement Details", tags: [ "tribble-reported", "C-enhancement" ] }
        - "<br/>"
        - { text: "I want to contribute to the code", link: "Contribute to the Code", tags: [ "tribble-reported" ] }
        - { text: "I want to contribute to the website", link: "Website", tags: [ "tribble-reported" ] }
        - { text: "I want to contribute to the documentation", link: "Docs", tags: [ "tribble-reported", "C-docs" ] }
        - "<br/>"
        - "If you'd like to report a bug in this system, please use the section for contributing to the documentation, and then report an issue in the docs."
      Enhancement Details:
        - "Great, thanks for helping us improve Perseus! Please fill in the following details about your feature request, and we'll look into it!"
        - "If your feature is related to a problem, please describe it here."
        - { id: "problem_desc", label: "Problem description", type: "multiline" }
        - { id: "enhancement_desc", label: "Describe your feature", type: "multiline" }
        - { id: "feat_willing_to_impl", label: "Are you willing to try to implement this yourself?", type: "boolean", tags: [ "author-willing-to-impl" ] }
        - { text: "Continue", link: "endpoint:Request Enhancement", tags: [] }
      Bug Type:
        - "Please select the type of bug you'd like to report."
        - { text: "I want to report an issue with the CLI", link: "Bug Details", tags: [ "A-cli" ] }
        - { text: "I want to report an issue with deployment", link: "Bug Details", tags: [ "A-deployment" ] }
        - { text: "I want to report an issue with testing", link: "Bug Details", tags: [ "A-testing" ] }
        - { text: "I want to report an issue with plugins", link: "Bug Details", tags: [ "A-plugins" ] }
        - "<br/>"
        - { text: "I want to report another bug", link: "Bug Details", tags: [] }
      Bug Details:
        - "Thanks for letting us know! Please fill in the following details so we can understand your issue."
        - { id: "bug_desc", label: "Describe the bug", type: "multiline" }
        - { id: "repro_steps", label: "How could someone reproduce this bug?", type: "multiline" }
        - "If your bug is complex, please create a minimum reproducible example, a repository that showcases the bug with the smallest amount of code possible. This helps maintainers solve your issue more quickly. You can leave this blank if you want to though, but an MRE will be necessary for more complex bugs."
        - { id: "mre_url", label: "Minimum reproducible example repo", type: "text", optional: true }
        - "You can check if a bug still occurs without hydration by removing the `hydrate` feature."
        - { id: "hydration_related", label: "Does it work if you disable hydration?", type: "boolean", tags: [ "A-hydration" ] }
        - "<br/>"
        - { id: "bug_willing_to_fix", label: "Are you willing to try to fix this yourself?", type: "boolean", tags: [ "author-willing-to-impl" ] }
        - { text: "Continue", link: "endpoint:Report Bug", tags: [] }

      Contribute to the Code:
        - "Thank you very much, your help is greatly appreciated! Please select one of the following ways you'd like to help out Perseus."
        - "Note: if you're looking to translate the website or the documentation, please go back and select one of the other options on the starting page."
        - { text: "I want to add a new server integration", link: "endpoint:Add Server Integration", tags: [] }
        - { text: "I want to add a new i18n backend", link: "endpoint:Add I18n Backend", tags: [] }
        - "<br/>"
        - { text: "I want to contribute some other way", link: "endpoint:General PR", tags: [] }

      Website:
        - "How would you like to contribute to the website?"
        - { text: "I want to report an issue", link: "Website Issue Details", tags: [ "C-bug", "A-website" ] }
        - { text: "I want to suggest a feature", link: "Enhancement Details", tags: [ "C-enhancement", "A-website" ] }
        - "<br/>"
        - { text: "I want to add my plugin to the plugins registry", link: "Plugin Details", tags: [ "C-enhancement", "A-new-plugin" ] }
        - { text: "I want to add a comparison", link: "endpoint:Add Comparison", tags: [] }
        - { text: "I want to translate the website", link: "endpoint:Translate Website", tags: [] }
        - { text: "I want to make another change myself", link: "endpoint:General PR", tags: [] }
        - "<br/>"
        # Someone will click this wanting to change things in the book, so here are the links for that (again)
        - { text: "I want to contribute to the book (on the website)", link: "Website Docs", tags: [ "A-website-docs" ] }
      Website Issue Details:
        - "Great, thanks for helping us improve the Perseus website! Please fill in the following details to help us understand your issue."
        - "Please note that this form is only for bugs **not** relating to the documentation on the website. If you want to report one of those, please go back and use the option for contributing to the book."
        - { id: "website_issue_page_url", label: "Which URL does the bug occur on?", type: "text" }
        - "Please select one or more of the following categories to help us understand the bug. If none of them fit, please fill in the 'other' field."
        - { id: "website_issue_categories", label: "Which of the following is your bug to do with?", can_select_multiple: true, options: [
            { text: "Styling", tags: [  ] },
            { text: "Mobile", tags: [  ] },
            { text: "Accessibility", tags: [  ] },
            { text: "Typos and grammar errors", tags: [  ] }
          ] }
        - { id: "website_issue_other_category", optional: true, label: "Other", type: "text" }
        - { id: "website_issue_desc", label: "Please describe the bug", type: "multiline" }
        - { text: "Continue", link: "endpoint:Report Website Issue", tags: [] }
      Plugin Details:
        - "Great, thanks for contributing to the community! Please fill out the following details, and a maintainer will add your plugin to the list."
        - { id: "plugin_name", label: "What's your plugin's name?", type: "text" }
        - { id: "plugin_author", label: "What's your author handle?", type: "text" }
        - { id: "plugin_desc", label: "Describe your plugin briefly", type: "text" }
        - { id: "plugin_url", label: "What's your plugin's homepage?", type: "text" }
        - "If you'd like to get a little tick next to your plugin that shows that it's been reviewed for quality and safety, you can apply by checking the following input. This is in no way essential, and it will slow down the process of acceptance (because a maintainer has to find time to review your whole plugin)."
        - { id: "plugin_applying_for_trust", label: "Would you like your plugin to be reviewed?", type: "boolean", tags: [ "E-plugin-review" ] }
        - { text: "Continue", link: "endpoint:Submit Plugin", tags: [] }
      Docs:
        - "The Perseus documentation is split into three main parts. Which one do you want to contribute to? If you just want to report an issue in any of them (not fixing it yourself, no shame in that), please select the first option."
        - { text: "I want to report an issue in the docs", link: "Docs Issue Details", tags: [ "C-bug" ] }
        - "<br/>"
        - { text: "I want to contribute to the book (on the website)", link: "Website Docs", tags: [ "A-website-docs" ] }
        - { text: "I want to contribute to the API documentation (on docs.rs)", link: "endpoint:API Docs", tags: [ "A-api-docs" ] }
        - { text: "I want to contribute to the repo docs (e.g. README, CHANGELOG, etc.)", link: "endpoint:Repo Docs", tags: [ "A-repo-docs" ] }
        - "<br/>"
        - { text: "I want to translate the docs (any of them)", link: "endpoint:Translate Docs", tags: [] }
      Website Docs:
        - "What exactly do you want to do with the documentation hosted on the website?"
        - { text: "Change some content on an existing page", link: "endpoint:Change Existing Content in Book", tags: [] }
        - { text: "Add some new pages", link: "endpoint:Add New Pages to Book", tags: [] }
      Docs Issue Details:
        - "Great, thanks for helping us make the Perseus documentation better! Please fill in these details to help us understand your issue."
        - { id: "docs_version", label: "Which version(s) of the docs is/are affected?", default: "v0.3.2", type: "text" }
        - { id: "docs_source", label: "Where are these docs?", options: [
            { text: "On the website (book)", tags: [ "A-website-docs" ] },
            { text: "On docs.rs (API)", tags: [ "A-api-docs" ] },
            { text: "In the repo (README, etc.)", tags: [ "A-repo-docs" ] }
          ] }
        - { id: "docs_issue_desc", label: "Please describe the issue", type: "multiline" }
        - { text: "Continue", link: "endpoint:Report Docs Issue", tags: [] }
    index: "Start"
    endpoints:
      General PR: "Great, thanks for contributing! Please make your changes in a pull request and then submit it to us (if you're unfamiliar with this process, please see [here](https://github.com/framesurge/perseus/blob/main/contributing.md#)). If you need any help, feel free to ask on our [Discord channel on the Sycamore server](https://discord.com/invite/GNqWYWNTdp). Also, [this](https://framesurge.sh/perseus/en-US/docs/advanced/arch) section in the documentation may come in handy."

      Report Bug:
        preamble: "Thanks for that, we'll look into the issue as soon as possible! Please press the button below to report the following issue through GitHub. If there are any issues, you can go back now and change things, but please don't change the issue body itself (it's auto-generated)."
        text: "This issue is reporting a bug in the code of Perseus. Details of the scope will be available in issue labels.

        The author described their issue as follows:

        > ${bug_desc}


        The steps to reproduce this issue are as follows:

        > ${repro_steps}


        A minimum reproducible example is available at <${mre_url}>.

        - Hydration-related: ${hydration_related}

        - The author is willing to attempt a fix: ${bug_willing_to_fix}
        "
        dest_text: "Report on GitHub"
        dest_url: "https://github.com/framesurge/perseus/issues/new?body=%s"
      Request Enhancement:
        preamble: "Thanks for the idea, we'll take a look! Please press the button below to report the following issue to us. If anything looks incorrect, you can go back and change it now (but please don't edit the final issue body, it's auto-generated)."
        text:
          "This issue is requesting an enhancement to Perseus. Details of the scope will be available in issue labels.

          The user described the problem related to this request as follows:

          > ${problem_desc}


          The user described the issue as follows:

          > ${enhancement_desc}

          - The author is willing to attempt an implementation: ${feat_willing_to_impl}
          "
        dest_text: "Submit on GitHub"
        dest_url: "https://github.com/framesurge/perseus/issues/new?body=%s"

      Add Server Integration: "Perseus currently supports using Actix Web and Warp as server backends, though, long-term, we'd like to support as many different servers as possible! Implementing a new integration can be difficult, but most of the utilities you'll need can be found in `packages/perseus/server/`. It's best to use `packages/perseus-actix-web/` as a guide, and note that your integration will be a new Rust package. The best way to build an integration is to look through the code of the existing ones, but if you need any help, feel free to ask on [our Discord channel on the Sycamore server](https://discord.com/invite/GNqWYWNTdp)!"
      Add I18n Backend: "Perseus currently uses [Fluent](https://projectfluent.org) for internationalization, but it can be extended to support alternatives. If you'd like to add another i18n backend to Perseus, you'll need to add a new file to `packages/perseus/src/translator` based on the `fluent.rs` file in that directory. Perseus doesn't use a trait to support i18n backends because of the potentially different arguments that each translator can take. This means you'll have to manually ensure that you implement all the required methods, as well as the `t!` and `link!` macros. A selection of errors is available for you to use, which you can add it to if absolutely necessary.<br/>If you're unfamiliar with the process of forking and making pull requests, please see [here](https://github.com/framesurge/perseus/blob/main/CONTRIBUTING.md#)."

      Submit Plugin:
        preamble: "Thanks for submitting your plugin! We'll try to review it and add it as soon as possible, but, especially if you've requested full code review, this could take a while. Please press the button below to report the following issue to us. If anything looks incorrect, you can go back and change it now (but please don't edit the final issue body, it's auto-generated)."
        text:
          "This issue is requesting the addition of a new plugin to the plugins resgistry.

          This is an automatically generated file to add to `website/plugins/en-US/` if the plugin passes review.

          ```json

          {
              \"name\": \"${plugin_name}\",
              \"description\": \"${plugin_desc}\",
              \"author\": \"${plugin_author}\",
              \"url\": \"${plugin_url}\",
              \"trusted\": ${plugin_applying_for_trust}
          }

          ```

          - Full plugin code review requested: ${plugin_applying_for_trust}
          "
        dest_text: "Submit on GitHub"
        dest_url: "https://github.com/framesurge/perseus/issues/new?body=%s"
      Report Docs Issue:
        preamble: "Thanks for reporting your issue! Please press the button below to report the following issue to us. If anything looks incorrect, you can go back and change it now (but please don't edit the final issue body, it's auto-generated)."
        text:
          "This issue is reporting a bug in the documentation.

          - Documentation version: ${docs_version}

          - Documentation source: ${docs_source}

          The user described the issue as follows:

          > ${docs_issue_desc}
          "
        dest_text: "Report on GitHub"
        dest_url: "https://github.com/framesurge/perseus/issues/new?body=%s"
      Change Existing Content in Book: "If you want to edit the book in some way that doesn't involve adding new pages, you can do this easily by just editing the Markdown files in the `docs/` folder. There's a subfolder in there for each major version of Perseus, so please make sure you change the documentation in all relevant versions. Please note that you can link to other pages in the docs by using `:<file-path>` (no file extension) as the Markdown link target, which avoids having to specify the version and locale. You can preview your changes after running `bonnie setup` (which will ask you to install some prerequisites) by running `bonnie site`. This runs three commands in parallel, and building the website for the first time will take some time. When it's ready, you'll be able to load <http://localhost:8080> in your browser to preview how your changes will look on the website. After your PR is merged, they'll be automatically applied to the global version of the website.<br/>If you're unfamiliar with the process of forking and making pull requests, please see [here](https://github.com/framesurge/perseus/blob/main/CONTRIBUTING.md#)."
      API Docs: "The documentation on docs.rs is generated by `cargo` from rust comments in the source code, which you can modify directly in the repository. when you're done, you can use `cargo doc` to preview your changes (this will generate documentation in `target/` which you'll then need to open in a browser).<br/>If you're unfamiliar with the process of forking and making pull requests, please see [here](https://github.com/framesurge/perseus/blob/main/contributing.md#)."
      Repo Docs: "The documentation in the repository is stored as a collection of simple Markdown files. You can make changes to these files without having to worry about any build processes, and then you can open a pull request when you're done. Please make sure you've used consistent formatting and correct grammar before submitting, but if you're unsure of anything, just mention it in your PR, and we'll be happy to help you out in review (especially if English isn't your first language)!<br/>If you're unfamiliar with the process of forking and making pull requests, please see [here](https://github.com/framesurge/perseus/blob/main/CONTRIBUTING.md#)."
      Add New Pages to Book: "Adding new pages to the book involves creating them in the appropriate version folder in `docs/` (please add your new pages to every relevant version) and then registering your new pages in that version's `SUMMARY.md` file. This is a file that's rendered from Markdown as the sidebar on the website, and you should add your pages as list entries to it (nesting is fully possible here). Notably, each list item must be a link, with its name in square brackets and the link text being `/docs/<path-to-your-file-in-the-filesystem>`. No `.md` file extension should be included. If you're unsure if what you've done has worked, or you just want to see your work, you can preview your changes after running `bonnie setup` (which will ask you to install some prerequisites) by running `bonnie site`. This runs three commands in parallel, and building the website for the first time will take some time. When it's ready, you'll be able to load <http://localhost:8080> in your browser to preview how your changes will look on the website. After your PR is merged, they'll be automatically applied to the global version of the website. Please also note that you can link to other pages in the docs by using `:<file-path>` (no file extension) as the Markdown link target, which avoids having to specify the version and locale.<br/>If you're unfamiliar with the process of forking and making pull requests, please see [here](https://github.com/framesurge/perseus/blob/main/CONTRIBUTING.md#)."
      Add Comparison: "You can easily add a new comparison to the website by copying one of the files in `website/comparisons/` and renaming it to be a machine-readable version of the framework name. Then, alter its contents to reflect the comparison's features (you can see the details of what each field means on [the comparisons page](https://framesurge.sh/perseus/en-US/comparisons)). To obtain Lighthouse scores for the comparison, please use <https://pagespeed-insights.com> and point it at a website built with the framework (preferably their own website, but this may not be possible if they're using a third-party documentation provider). Please note that these scores will be double-checked in your PR, and, if there's a major discrepancy between the scores you provide and the scores the reviewer gets, you may be asked to provide screenshots.<br/>Editing an existing comparison should be a very similar process, though please explain in your PR exactly why you're editing it (e.g. a new version has been released that changes its Lighthouse scores or adds new features).<br/>If you're unfamiliar with the process of forking and making pull requests, please see [here](https://github.com/framesurge/perseus/blob/main/CONTRIBUTING.md#)."
      Report Website Issue:
        preamble: "Thanks for reporting your issue! Please press the button below to report the following issue to us. If anything looks incorrect, you can go back and change it now (but please don't edit the final issue body, it's auto-generated)."
        text:
          "This issue is reporting a bug in the website.

          - The issue occurred on <${website_issue_page_url}>.

          - Issue categories: ${website_issue_categories}

          - Other category: ${website_issue_other_category}

          The user described the issue as follows:

          > ${website_issue_desc}
          "
        dest_text: "Report on GitHub"
        dest_url: "https://github.com/framesurge/perseus/issues/new?body=%s"
      Translate Docs: "First off, thank you so much for offering to translate the documentation, it's one of the best ways to help Perseus grow! This will be a big job, but it should be as convenient as possible. The documentation on the website can be translated by writing new Markdown files under `docs/<version>/<locale>` (currently there's just `en-US`). Unlike the rest of the website, the documentation can be translated in parts, as long as you note that it's a work in progress. Please note though that you'll need to create at least a partial translation for *every* version of Perseus. That said, there's not a lot of point in translating the v0.1.x documentation, since it's so obsolete, so you might just have an introduction page there in the new language that states that the version isn't supported in this language. If you perform a partial translation for a version (as in translating multiple pages), please create a page for every page in the source language (`en-US`), and just note on the pages you haven't done yet that they're untranslated for now (do not omit pages fully, this can cause problems).<br/>If you're unfamiliar with the process of forking and making pull requests, please see [here](https://github.com/framesurge/perseus/blob/main/CONTRIBUTING.md#)."
      Translate Website: "First off, thank you so much for offering to translate the website, it's one of the best ways to help Perseus grow! The Perseus website is already fully enabled for i18n, and all you need to do to translate it is add new `<locale>.ftl` files under `website/translations/`. Currently, there's just an `en-US.ftl` file there, which contains all the translation IDs needed. If you wanted to translate the website into, say, Russian, you'd create duplicate that file and rename the copy to `ru-RU.ftl`, and then you'd translate each of the IDs inside.<br/>When you're done, please add the new locale to `website/src/lib.rs` (only if the documentation has also been translated into this language though).<br/>If you're unfamiliar with the process of forking and making pull requests, please see [here](https://github.com/framesurge/perseus/blob/main/CONTRIBUTING.md#)."