Sintaxe para formulários de problema

Você pode definir diferentes tipos de entrada, validações, responsáveis padrão e etiquetas padrão para seus formulários de problemas.

Neste artigo

Nota: formulários de problemas estão atualmente em versão prévia pública e sujeitos a alterações.

Sobre a sintaxe do YAML para formulários de problemas

Crie formulários de problemas personalizados adicionando um arquivo de definição de formulário YAML à pasta /.github/ISSUE_TEMPLATE no repositório. Se você não estiver familiarizado com o YAML e quiser saber mais, confira "Aprenda a usar o YAML em Y minutos". Você pode definir diferentes tipos de entrada, validações, atribuídos padrão e etiquetas padrão para seus formulários de problemas.

Quando um contribuidor preenche um formulário de problemas, as suas respostas para cada entrada são convertidas em markdown e adicionadas ao corpo de um issue. Os contribuidores podem editar seus problemas criados com formulários de problemas e outras pessoas podem interagir com problemas como um problema criado por meio de outros métodos.

Os formulários de problemas não são compatíveis com pull requests. É possível criar modelos de pull request nos seus repositórios para os colaboradores usarem. Para obter mais informações, confira "Criar modelos de pull request no repositório".

Este exemplo de arquivo de configuração YAML define um formulário de problema utilizando várias entradas para reportar um erro.

Nota: a chave do campo required só tem suporte em repositórios públicos. Em repositórios privados e internos, todos os campos são opcionais.

YAML
name: Bug Report
description: File a bug report.
title: "[Bug]: "
labels: ["bug", "triage"]
projects: ["octo-org/1", "octo-org/44"]
assignees:
  - octocat
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  - type: input
    id: contact
    attributes:
      label: Contact Details
      description: How can we get in touch with you if we need more info?
      placeholder: ex. email@example.com
    validations:
      required: false
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Also tell us, what did you expect to happen?
      placeholder: Tell us what you see!
      value: "A bug happened!"
    validations:
      required: true
  - type: dropdown
    id: version
    attributes:
      label: Version
      description: What version of our software are you running?
      options:
        - 1.0.2 (Default)
        - 1.0.3 (Edge)
      default: 0
    validations:
      required: true
  - type: dropdown
    id: browsers
    attributes:
      label: What browsers are you seeing the problem on?
      multiple: true
      options:
        - Firefox
        - Chrome
        - Safari
        - Microsoft Edge
  - type: textarea
    id: logs
    attributes:
      label: Relevant log output
      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
      render: shell
  - type: checkboxes
    id: terms
    attributes:
      label: Code of Conduct
      description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com). 
      options:
        - label: I agree to follow this project's Code of Conduct
          required: true

Sintaxe de nível superior

Todos os arquivos de configuração do formulário de problema precisam começar com os pares chave-valor name, description e body.

YAML
name:
description:
body:

Você pode definir as seguintes chaves de nível superior para cada formulário de problema.

ChaveDescriçãoObrigatórioTipo
nameUm nome para o modelo de formulário de problema. Deve ser exclusivo de todos os outros modelos, incluindo modelos de markdown.ObrigatórioString
descriptionUma descrição para o modelo de formulário de problema, que aparece na interface de modelo de seletor.ObrigatórioString
bodyDefinição dos tipos de entrada no formulário.ObrigatórioArray
assigneesAs pessoas que serão automaticamente atribuídas a problemas criados com este modelo.OpcionalMatriz ou strings delimitadas por vírgula
labelsEtiquetas que serão adicionadas automaticamente a problemas criados com este modelo. Se um rótulo ainda não existir no repositório, ele não será adicionado automaticamente ao problema.OpcionalMatriz ou strings delimitadas por vírgula
titleUm título padrão que será preenchido no formulário de envio do problema.OpcionalString
projectsProjetos aos quais quaisquer problemas criados com esse modelo serão adicionados automaticamente. O formato dessa chave é PROJECT-OWNER/PROJECT-NUMBER.
Nota: A pessoa que abre o problema deve ter permissões de gravação para os projetos especificados. Se você não espera que as pessoas que usam esse modelo tenham acesso de gravação, considere habilitar o fluxo de trabalho de adição automática do seu projeto. Para saber mais, confira "Adicionar itens automaticamente".
OpcionalMatriz ou strings delimitadas por vírgula

Para os tipos de entrada body disponíveis e suas sintaxes, confira "Sintaxe para o esquema de formulário do GitHub".

Convertendo um modelo de problema de markdown em um modelo de formulário de problema de YAML

Você pode usar os modelos de problemas de markdown e YAML no seu repositório. Se você deseja converter um modelo de problema de markdown em um modelo de formulário de problema de YAML, você deverá criar um novo arquivo YAML para definir o formulário de problema. Você pode transpor manualmente um modelo de problema de markdown existente para um formulário de problema de YAML. Para obter mais informações, confira "Configurando modelos de problemas em seu repositório".

Se quiser usar o mesmo nome de arquivo para o seu formulário de problema de YAML, você deverá excluir o modelo de problema do markdown quando fizer commit do novo arquivo no seu repositório.

Um exemplo de um modelo de problema de markdown e um modelo de formulário de problema de YAML correspondente é indicado abaixo.

Modelo de problema de markdown

Markdown
---
name: 🐞 Bug
about: File a bug/issue
title: '[BUG] <title>'
labels: Bug, Needs Triage
assignees: ''

---

<!--
Note: Please search to see if an issue already exists for the bug you encountered.
-->

### Current Behavior:
<!-- A concise description of what you're experiencing. -->

### Expected Behavior:
<!-- A concise description of what you expected to happen. -->

### Steps To Reproduce:
<!--
Example: steps to reproduce the behavior:
1. In this environment...
1. With this config...
1. Run '...'
1. See error...
-->

### Environment:
<!--
Example:
- OS: Ubuntu 20.04
- Node: 13.14.0
- npm: 7.6.3
-->

### Anything else:
<!--
Links? References? Anything that will give us more context about the issue that you are encountering!
-->

Modelo de formulário de problema de YAML

YAML
name: 🐞 Bug
description: File a bug/issue
title: "[BUG] <title>"
labels: ["Bug", "Needs Triage"]
body:
- type: checkboxes
  attributes:
    label: Is there an existing issue for this?
    description: Please search to see if an issue already exists for the bug you encountered.
    options:
    - label: I have searched the existing issues
      required: true
- type: textarea
  attributes:
    label: Current Behavior
    description: A concise description of what you're experiencing.
  validations:
    required: false
- type: textarea
  attributes:
    label: Expected Behavior
    description: A concise description of what you expected to happen.
  validations:
    required: false
- type: textarea
  attributes:
    label: Steps To Reproduce
    description: Steps to reproduce the behavior.
    placeholder: |
      1. In this environment...
      1. With this config...
      1. Run '...'
      1. See error...
  validations:
    required: false
- type: textarea
  attributes:
    label: Environment
    description: |
      examples:
        - **OS**: Ubuntu 20.04
        - **Node**: 13.14.0
        - **npm**: 7.6.3
    value: |
        - OS:
        - Node:
        - npm:
    render: markdown
  validations:
    required: false
- type: textarea
  attributes:
    label: Anything else?
    description: |
      Links? References? Anything that will give us more context about the issue you are encountering!

      Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
  validations:
    required: false

Leitura adicional