Syntaxe des formulaires de problème

Vous pouvez définir des types d’entrée, des validations, des personnes responsables par défaut et des étiquettes par défaut pour vos formulaires de problème.

Dans cet article

Remarque : Les formulaires de problème sont actuellement en version bêta et peuvent faire l’objet de modifications.

À propos de la syntaxe YAML des formulaires de problème

Vous pouvez créer des formulaires de problème personnalisés en ajoutant un fichier de définition de formulaire YAML au dossier /.github/ISSUE_TEMPLATE de votre dépôt. Si vous débutez avec YAML et souhaitez en savoir plus, consultez « Découvrir YAML en Y minutes ». Vous pouvez définir différents types d’entrée, des validations, des affectations de personnes responsables par défaut et des étiquettes par défaut pour vos formulaires de problème.

Quand un contributeur remplit un formulaire de problème, ses réponses pour chaque entrée sont converties en texte Markdown avant d’être ajoutées au corps d’un problème. Les contributeurs peuvent modifier leurs problèmes créés avec des formulaires de problème. Les autres personnes peuvent interagir avec ces problèmes, comme s’ils avaient été créés via d’autres méthodes.

Les formulaires de problème ne sont pas pris en charge pour les demandes de tirage. Vous pouvez créer des modèles de demande de tirage dans vos dépôts à l’intention des collaborateurs. Pour plus d’informations, consultez « Création d’un modèle de demande de tirage pour votre dépôt ».

Cet exemple de fichier config YAML définit un formulaire de problème à l’aide de plusieurs entrées pour signaler un bogue.

Remarque : La clé de champ required est uniquement prise en charge dans les dépôts publics. Dans les dépôts privés et internes, tous les champs sont facultatifs.

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

Syntaxe de niveau supérieur

Tous les fichiers config des formulaires de problème doivent commencer par les paires clé-valeur name, description et body.

YAML
name:
description:
body:

Vous pouvez définir les clés de niveau supérieur suivantes pour chaque formulaire de problème.

CléDescriptionObligatoireType
nameNom du modèle de formulaire de problème. Doit être unique par rapport à tous les autres modèles, notamment les modèles Markdown.ObligatoireString
descriptionDescription du modèle de formulaire de problème, qui apparaît dans l’interface du sélecteur de modèles.ObligatoireString
bodyDéfinition des types d’entrée dans le formulaire.ObligatoireArray
assigneesPersonnes affectées automatiquement aux problèmes créés avec ce modèle.FacultatifTableau ou chaîne délimitée par des virgules
labelsÉtiquettes ajoutées automatiquement aux problèmes créés avec ce modèle. Si une étiquette n’existe pas déjà dans le dépôt, elle n’est pas automatiquement ajoutée au problème.FacultatifTableau ou chaîne délimitée par des virgules
titleTitre par défaut prérempli dans le formulaire d’envoi du problème.FacultatifString
projectsProjets auxquels toutes les questions créées avec ce modèle seront automatiquement ajoutées. Le format de cette clé est PROJECT-OWNER/PROJECT-NUMBER.
Note : La personne qui ouvre le dossier doit avoir l’autorisation d’accès en écriture sur les projets spécifiés. Si vous ne vous attendez pas à ce que les personnes utilisant ce modèle aient un accès en écriture, envisagez d'activer le flux de travail d'ajout automatique de votre projet. Pour plus d'informations, voir « Ajouter des éléments automatiquement ».
FacultatifTableau ou chaîne délimitée par des virgules

Pour connaître les types d’entrée disponibles de body et leurs syntaxes, consultez « Syntaxe du schéma de formulaire de GitHub ».

Conversion d’un modèle de problème Markdown en modèle de formulaire de problème YAML

Vous pouvez utiliser les modèles de problème Markdown et YAML dans votre dépôt. Si vous souhaitez convertir un modèle de problème Markdown en modèle de formulaire de problème YAML, vous devez créer un fichier YAML pour définir le formulaire de problème. Vous pouvez transposer manuellement un modèle de problème Markdown existant en formulaire de problème YAML. Pour plus d’informations, consultez « Configuration des modèles de problème pour votre dépôt ».

Si vous souhaitez utiliser le même nom de fichier pour votre formulaire de problème YAML, vous devez supprimer le modèle de problème Markdown quand vous commitez le nouveau fichier dans votre dépôt.

Vous trouverez ci-dessous un exemple de modèle de problème Markdown et le modèle de formulaire de problème YAML correspondant.

Modèle de problème 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!
-->

Modèle de formulaire de problème 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

Pour aller plus loin