Sintaxis para el modelado de formato de GitHub

Puedes utilizar el modelado de formato de GitHub para configurar los formatos para las características compatibles.

Nota: El modelado de formatos de GitHub se encuentra actualmente en 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, consulta "Configurar plantillas de propuestas 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:
      - label: 1.0.2 (Default)
      - label: 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!"

Claves

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

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
typeEl tipo de elemento que quieres definir.RequeridoSecuencia
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
idEl identificador del elemento, excepto cuando el type se configura como markdown. Solo puede utilizar caracteres alfanuméricos, -, y _. Debe ser única en la definición de formato. Si se proporcionó, la id es el identificador canónico para el campo en los pre-llenados de parámetro de la consulta de URL.OpcionalSecuencia
attributesUn conjunto de pares clave-valor que definen las propiedades del elemento.RequeridoHash
validationsUn conjunto de pares de clave-valor que configuran las restricciones en el elemento.OpcionalHash

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

TypeDescripción
markdownEl texto de lenguaje de marcado se muestra en el formato para proporcionar contexto adicional al usuario, pero no se ha enviado.
textareaUn campo de texto de línea múltiple.
inputUn campo de texto de línea sencilla.
desplegableUn menú desplegable.
checkboxesUn conjunto de casillas de verificación.

markdown

Puedes utilizar un elemento de markdown para mostrar el lenguaje de marcado en tu formato que proporcione contexto adicional al usuario, pero que no se haya emitido.

Atributos

Para el valor de la clave attributes, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
valueEl texto se interpreta. El formateo en lenguaje de marcado es compatible.RequeridoSecuencia

Tips: El procesamiento de YAML tratará el símbolo de 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

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

textarea

Puedes utilizar un elemento de textarea para agregar un texto de línea múltiple a tu formato. Los contribuyentes también pueden adjuntar archivos en los campos de textarea.

Atributos

Para el valor de la clave attributes, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
etiquetaUna descripción breve de la entrada que se espera del usuario, lo cual también se muestra en el formato.RequeridoSecuencia
descripciónUna descripción del área de texto para proporcionar contexto u orientación, la cual se muestra en el formato.OpcionalSecuenciaSecuencia vacía
placeholderUn marcador de posición que interpreta en el área de texto cuando está vacía.OpcionalSecuenciaSecuencia vacía
valueEl texto se pre-llena en el área de texto.OpcionalSecuencia
renderSi 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.OpcionalSecuenciaLos lenguajes que conoce GitHub. Para obtener más información, consulta el archivo YAML de lenguajes.

Validaciones

Para el valor de la clave validations, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
requiredPreviene la emisión hasta que se complete el elemento.OpcionalBooleanofalso

Ejemplo

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

Puedes utilizar un elemento de input para agregar un campo de texto de línea sencilla a tu formato.

Atributos

Para el valor de la clave attributes, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
etiquetaUna descripción breve de la entrada que se espera del usuario, lo cual también se muestra en el formato.RequeridoSecuencia
descripciónUna descripción del campo para proporcionar contexto u orientación, la cual se muestra en el formato.OpcionalSecuenciaSecuencia vacía
placeholderUn marcador de posición semi-transparente que interpreta en el campo cuando está vacío.OpcionalSecuenciaSecuencia vacía
valueEl texto se pre-llenó en el campo.OpcionalSecuencia

Validaciones

Para el valor de la clave validations, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
requiredPreviene la emisión hasta que se complete el elemento.OpcionalBooleanofalso

Ejemplo

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 user account page (1-2 times a week)"
  validations:
    required: true

Puedes utilizar un elemento de dropdown para agregar un menú desplegable en tu formato.

Atributos

Para el valor de la clave attributes, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
etiquetaUna descripción de la entrada que se espera del usuario, lo cual también se muestra en el formato.RequeridoSecuencia
descripciónUna descripción del menú desplegable para proporcionar contexto adicional u orientación, la cual se muestra en el formato.OpcionalSecuenciaSecuencia vacía
multipleDetermina si el usuario puede seleccionar más de una opción.OpcionalBooleanofalse
optionsUn arreglo de opciones que puede elegir el usuario. No puede estar vacío y todas las elecciones deben ser distintas.RequeridoArreglo de secuencias

Validaciones

Para el valor de la clave validations, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
requiredPreviene la emisión hasta que se complete el elemento.OpcionalBooleanofalso

Ejemplo

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

Puedes utilizar el elemento de checkboxes para agregar un conjunto de casillas de verificación a tu formato.

Atributos

Para el valor de la clave attributes, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoValores válidos
etiquetaUna descripción de la entrada que se espera del usuario, lo cual también se muestra en el formato.OpcionalSecuencia
descripciónUna 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.OpcionalSecuenciaSecuencia vacía
optionsUn arreglo de casillas de verificación que puede seleccionar el usuario. Para conocer la sintaxis, consulta a continuación.RequeridoArreglo

Para cada valor en el arreglo de options, puedes configurar las siguientes claves.

ClaveDescripciónRequeridoTypePredeterminadoOpciones
etiquetaEl 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.RequeridoSecuencia
requiredPreviene la emisión hasta que se complete el elemento.OpcionalBooleanofalso

Ejemplo

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

Leer más

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.