Sintaxis para el modelado de formato de GitHub

Nota: El esquema de formato de GitHub se encuentra actualmente en versión beta y está sujeto a cambios.

Acerca del modelado de formatos de GitHub

Puedes utilizar el modelado de formato de GitHub para configurar los formatos para las características compatibles. Para obtener más información, vea «Configurar las plantillas de reporte de problemas para tu repositorio».

Un formato es un conjunto de elemotos para solicitar la aportación de un usuario. Puedes configurar un formato si creas una definición de formato YAML, la cual es un arreglo de elementos de formato. Cada elemento de formato es un conjunto de pares de valor-llave que determinan el tipo y las propiedades del elemento y las restricciones que quieres aplicarle. Para algunas claves, el valor es otro conjunto de pares de clave-valor.

Por ejemplo, la siguente definición de formato incluye cuatro elementos de formato: un área de texto para proporcionar el sistema operativo del usuario, un menú desplegable para elegir la versión de software que está ejecutando el usuario, una casilla de verificación para reconocer que se leyó y aceptó el código de conducta y el lenguaje de marcado que agradece al usuario por haber completado el formato.

YAML

- type: textarea
  attributes:
    label: Operating System
    description: What operating system are you using?
    placeholder: Example: macOS Big Sur
    value: operating system
  validations:
    required: true
- type: dropdown
  attributes:
    label: Version
    description: What version of our software are you running?
    multiple: false
    options:
      - 1.0.2 (Default)
      - 1.0.3 (Edge)
  validations:
    required: true
- type: checkboxes
  attributes:
    label: Code of Conduct
    description: The Code of Conduct helps create a safe space for everyone. We require
      that everyone agrees to it.
    options:
      - label: I agree to follow this project's [Code of Conduct](link/to/coc)
        required: true
- type: markdown
  attributes:
    value: "Thanks for completing our form!"

Teclas

Para cada elemento de formato, puedes configurar las siguientes claves.

Clave	Descripción	Tipo	Valores válidos
`type`	El tipo de elemento que quieres definir.	String	`checkboxes` `dropdown` `input` `markdown` `textarea`
`id`	Identificador del elemento, excepto cuando `type` se establece en `markdown`. Solo puede usar caracteres alfanuméricos, `-` y `_`. Debe ser única en la definición de formato. Si se proporciona, `id` es el identificador canónico para el campo en los valores previamente rellenados de parámetro de la consulta de URL.	String
`attributes`	Un conjunto de pares clave-valor que definen las propiedades del elemento.	Asignación
`validations`	Un conjunto de pares de clave-valor que configuran las restricciones en el elemento.	Asignación

Puedes elegir desde los siguientes tipos de elementos de formato. Cada tipo tiene atributos y validaciones únicos.

Tipo	Descripción
`markdown`	El texto de Markdown que se muestra en el formulario para proporcionar contexto adicional al usuario, pero que no se envía.
`textarea`	Un campo de texto de línea múltiple.
`input`	Un campo de texto de línea sencilla.
`dropdown`	Un menú desplegable.
`checkboxes`	Un conjunto de casillas de verificación.

`markdown`

Puede usar un elemento markdown para mostrar Markdown en el formulario que proporcione contexto adicional al usuario, pero que no se envíe.

Atributos para `markdown`

Para el valor de la clave attributes, puede establecer las claves siguientes.

Clave	Descripción	Obligatorio	Tipo	Valor predeterminado	Valores válidos
`value`	El texto se interpreta. El formateo en lenguaje de marcado es compatible.		String

Sugerencias: el procesamiento de YAML tratará el símbolo hash como un comentario. Para insertar encabezados con lenguaje de marcado, pon tu texto entre comillas.

Para el texto de línea múltiple, puedes utilizar el operador de pipa.

Ejemplo de `markdown`

YAML

body:
- type: markdown
  attributes:
    value: "## Thank you for contributing to our project!"
- type: markdown
  attributes:
    value: |
      Thanks for taking the time to fill out this bug report.

`textarea`

Puede usar un elemento textarea para agregar un campo de texto de varias líneas al formulario. Los colaboradores también pueden adjuntar archivos en campos textarea.

Atributos para `textarea`

Para el valor de la clave attributes, puede establecer las claves siguientes.

Clave	Descripción	Tipo	Valor predeterminado	Valores válidos
`label`	Una descripción breve de la entrada que se espera del usuario, lo cual también se muestra en el formato.	String
`description`	Una descripción del área de texto para proporcionar contexto u orientación, la cual se muestra en el formato.	String	Cadena vacía
`placeholder`	Un marcador de posición que interpreta en el área de texto cuando está vacía.	String	Cadena vacía
`value`	El texto se pre-llena en el área de texto.	String
`render`	Si se proporciona un valor, el texto emitido se formatea en un bloque de código. Cuando se proporciona esta llave, el áera de texto no se expandirá para los adjuntos de archivo o la edición de lenguaje de marcado.	String		Los lenguajes que conoce GitHub. Para más información, vea el archivo YAML de lenguajes.

Validaciones para `textarea`

Para el valor de la clave validations, puede establecer las claves siguientes.

Clave	Descripción	Obligatorio	Tipo	Valor predeterminado	Valores válidos
`required`	Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos.		Boolean	false

Ejemplo de `textarea`

YAML

body:
- type: textarea
  id: repro
  attributes:
    label: Reproduction steps
    description: "How do you trigger this bug? Please walk us through it step by step."
    value: |
      1.
      2.
      3.
      ...
    render: bash
  validations:
    required: true

`input`

Puede usar un elemento input para agregar un campo de texto de una sola línea al formulario.

Atributos para `input`

Para el valor de la clave attributes, puede establecer las claves siguientes.

Clave	Descripción	Tipo	Valor predeterminado
`label`	Una descripción breve de la entrada que se espera del usuario, lo cual también se muestra en el formato.	String
`description`	Una descripción del campo para proporcionar contexto u orientación, la cual se muestra en el formato.	String	Cadena vacía
`placeholder`	Un marcador de posición semi-transparente que interpreta en el campo cuando está vacío.	String	Cadena vacía
`value`	El texto se pre-llenó en el campo.	String

Validaciones para `input`

Para el valor de la clave validations, puede establecer las claves siguientes.

Clave	Descripción	Obligatorio	Tipo	Valor predeterminado	Valores válidos
`required`	Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos.		Boolean	false

Ejemplo de `input`

YAML

body:
- type: input
  id: prevalence
  attributes:
    label: Bug prevalence
    description: "How often do you or others encounter this bug?"
    placeholder: "Example: Whenever I visit the personal account page (1-2 times a week)"
  validations:
    required: true

Puede usar un elemento dropdown para agregar un menú desplegable en el formulario.

Para el valor de la clave attributes, puede establecer las claves siguientes.

Clave	Descripción	Tipo	Valor predeterminado
`label`	Una descripción de la entrada que se espera del usuario, lo cual también se muestra en el formato.	String
`description`	Una descripción del menú desplegable para proporcionar contexto adicional u orientación, la cual se muestra en el formato.	String	Cadena vacía
`multiple`	Determina si el usuario puede seleccionar más de una opción.	Boolean	false
`options`	Un arreglo de opciones que puede elegir el usuario. No puede estar vacío y todas las elecciones deben ser distintas.	Matriz de cadena

Para el valor de la clave validations, puede establecer las claves siguientes.

Clave	Descripción	Obligatorio	Tipo	Valor predeterminado	Valores válidos
`required`	Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos.		Boolean	false

YAML

body:
- type: dropdown
  id: download
  attributes:
    label: How did you download the software?
    options:
      - Homebrew
      - MacPorts
      - apt-get
      - Built from source
  validations:
    required: true

`checkboxes`

Puede usar el elemento checkboxes para agregar un conjunto de casillas al formulario.

Atributos para `checkboxes`

Para el valor de la clave attributes, puede establecer las claves siguientes.

Clave	Descripción	Tipo	Valor predeterminado
`label`	Una descripción de la entrada que se espera del usuario, lo cual también se muestra en el formato.	String
`description`	Una descripción del conjunto de casillas de verificación, la cual se muestra en el formato. Es compatible con el formateo de lenguaje de marcado.	String	Cadena vacía
`options`	Un arreglo de casillas de verificación que puede seleccionar el usuario. Para conocer la sintaxis, consulta a continuación.	Array

Para cada valor de la matriz options, puede establecer las siguientes claves.

Clave	Descripción	Obligatorio	Tipo	Valor predeterminado	Opciones
`label`	El identificador para la opción, el cual se muestra en el formato. Hay compatibilidad con lenguaje de marcado para formateo de texto en itálicas o negritas y para los hipervínculos.		String

Validaciones para `checkboxes`

Para el valor de la clave validations, puede establecer las claves siguientes.

Clave	Descripción	Obligatorio	Tipo	Valor predeterminado	Valores válidos
`required`	Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos.		Boolean	false

Ejemplo de `checkboxes`

YAML

body:
- type: checkboxes
  id: operating-systems
  attributes:
    label: Which operating systems have you used?
    description: You may select more than one.
    options:
      - label: macOS
      - label: Windows
      - label: Linux

Información adicional

YAML

Sintaxis para el modelado de formato de GitHub

En este artículo