Créer une documentation utilisateur pour votre extension

Chaque extension doit être accompagnée d'une documentation expliquant aux utilisateurs ce qu'elle fait et comment l'utiliser.

La documentation minimale requise est cet ensemble de trois fichiers Markdown :

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

Vous devriez également envisager de produire :

• Un fichier README pour le dépôt public de l'extension.
• Tutoriels, guides et références plus longs publiés sur votre propre site Web et associés à votre PREINSTALL.md.

Pour découvrir les bonnes pratiques, les expressions et la structure courantes, nous vous recommandons de consulter les fichiers disponibles avec les extensions Firebase officielles.

Créer un fichier README

Votre répertoire d'extensions peut éventuellement contenir un fichier README. Notez que la commande firebase ext:dev:init n'en génère pas automatiquement pour vous.

Toutefois, la CLI Firebase est compatible avec la commande pratique suivante pour générer automatiquement un fichier README contenant le contenu extrait de vos fichiers extension.yaml et PREINSTALL.md :

firebase ext:info ./path/to/extension --markdown > README.md

Tous les fichiers README des extensions Firebase officielles sont générés à l'aide de cette commande.

Ajouter des informations sur l'installation

Une fois que vous avez rédigé ou généré un fichier README, ajoutez-y des informations sur l'installation. Vous pouvez utiliser l'extrait suivant comme modèle :

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][install-link]

[install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name

### Firebase CLI

```bash
firebase ext:install publisher_id/extension_name --project=[your-project-id]
```

> Learn more about installing extensions in the Firebase Extensions documentation:
> [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console),
> [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)

---

Écrire un fichier PREINSTALL

Le fichier PREINSTALL est une présentation de votre extension, une sorte de page "marketing".

Quel est le contenu de ce fichier ?

• Description complète des fonctionnalités de votre extension
• Liste des prérequis, comme la configuration de la base de données ou l'accès à un service non Google (exemple)
• Brève description des tâches de pré-installation et des instructions associées
• Brève description des tâches post-installation (exemple) (les instructions détaillées sont à insérer dans POSTINSTALL)
• Brève description des implications en termes de facturation (commencez par le texte standard)

Où ce contenu s'affiche-t-il pour l'utilisateur ?

Console Firebase">

Console Firebase">

• Sur la page de l'extension sur extensions.dev.
• Dépôt de code source de votre extension (dans le répertoire de l'extension)
• Dans le fichier README de l'extension (si vous utilisez l'option --markdown > README.md de la CLI Firebase)

Les fichiers PREINSTALL ne peuvent pas accéder aux valeurs de paramètre de l'extension. Vous ne devez donc pas vous attendre à ce que les références de paramètre s'affichent avec des valeurs réelles.

Quelles sont les bonnes pratiques à suivre ?

• Si possible, limitez le contenu complet du fichier PREINSTALL à une seule page.
• Fournissez le niveau de détail dont un utilisateur final a absolument besoin avant d'installer l'extension.
• Fournissez des instructions détaillées dans le fichier POSTINSTALL ou dans d'autres fichiers supplémentaires.
• Indiquez brièvement si vous fournissez d'autres outils ou scripts pour prendre en charge l'extension.

Billing

This extension uses other Firebase or Google Cloud services which may have
  associated charges:

*   <list Google services / products that your extension uses>
*   <list Firebase services that your extension uses>
*   Cloud Secret Manager <if the extension uses secret params>
*   Cloud Functions

When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)

<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.

Écrire un fichier POSTINSTALL

Le fichier POSTINSTALL est la page d'instructions détaillées de votre extension après l'installation.

Quel est le contenu de ce fichier ?

• Instructions détaillées pour toutes les tâches requises après l'installation, comme la configuration des règles de sécurité Firebase ou l'ajout de code côté client (exemple)
• Instructions génériques pour essayer immédiatement l'extension installée (par exemple, "accédez à la console, puis faites ceci")
• Informations de base sur le déclenchement de l'extension, en particulier pour les extensions déclenchées par une requête HTTP
• Brèves instructions pour surveiller l'extension installée (commencez par le texte standard)

Où ce contenu s'affiche-t-il pour l'utilisateur ?

Console Firebase">

Console Firebase">

• Dans la console Firebase après qu'un utilisateur a installé votre extension (dans la fiche d'informations de l'extension installée)

  • Assurez-vous d'examiner l'affichage du contenu POSTINSTALL en installant votre extension dans un projet réel.

• Dépôt de code source de votre extension (dans le répertoire de l'extension)

Les fichiers POSTINSTALL peuvent accéder aux valeurs des paramètres et à plusieurs variables liées aux fonctions de l'extension. Lorsque le contenu POSTINSTALL s'affiche dans la console Firebase, les valeurs réelles s'affichent plutôt que les références de paramètre ou de variable. Découvrez ci-dessous comment faire référence à des paramètres et des variables dans votre fichier POSTINSTALL.

Quelles sont les bonnes pratiques à suivre ?

• Le contenu complet du fichier POSTINSTALL doit être concis, mais descriptif.
• Divisez le contenu en sections à l'aide de titres pour séparer les tâches ou les concepts distincts.
• Envisagez de publier des instructions détaillées pour un workflow ou une tâche spécifique sur votre site Web (exemple) ou dans des fichiers Markdown supplémentaires dans le dépôt d'extensions (exemple).
• Faites référence aux paramètres et aux variables liées aux fonctions afin que l'utilisateur voie leurs valeurs configurées dans le contexte des instructions.

Référencer des paramètres et des variables

Une fois l'installation terminée, la console Firebase affiche le contenu du fichier POSTINSTALL de l'extension. Si vous référencez des paramètres et des variables liées aux fonctions (voir le tableau ci-dessous) dans votre fichier POSTINSTALL, la console remplit ces références avec les valeurs réelles de l'instance installée.

Accédez aux valeurs des paramètres configurés dans le fichier POSTINSTALL à l'aide de la syntaxe suivante : ${param:PARAMETER_NAME}.

Vous pouvez également référencer les variables liées aux fonctions suivantes dans votre fichier POSTINSTALL uniquement. Firebase est compatible avec ces variables pour vous permettre de fournir plus facilement des conseils à vos utilisateurs après l'installation. Vous ne pouvez les utiliser que dans le fichier POSTINSTALL, car les valeurs de ces variables ne sont disponibles qu'après l'installation.

Dans ce tableau, function-name correspond à la valeur du champ name dans l'objet de ressource de la fonction dans extension.yaml.

Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.

Documenter le déclenchement d'une extension

Dans la documentation utilisateur de votre extension, vous devez indiquer à vos utilisateurs comment déclencher votre extension. Ces instructions peuvent être aussi détaillées que vous le jugez nécessaire, mais gardez à l'esprit les bonnes pratiques pour écrire un fichier POSTINSTALL. Pour savoir comment fournir ces instructions, développez la section ci-dessous qui s'applique à votre extension.

Écrire un fichier CHANGELOG

Quel est le contenu de ce fichier ?

Chaque extension doit disposer d'un fichier CHANGELOG.md qui documente les modifications incluses dans chaque nouvelle version de votre extension que vous publiez. Placez chaque version sous un en-tête de niveau 2 (##). Sinon, vous pouvez utiliser la mise en forme Markdown de votre choix.

L'exemple suivant est un extrait de l'une des extensions officielles :

## Version 0.1.3

feature - Support deletion of directories (issue #148).

## Version 0.1.2

feature - Add a new param for recursively deleting subcollections in Cloud
Firestore (issue #14).

fixed - Fixed "cold start" errors experienced when the extension runs after a
period of inactivity (issue #48).

## Version 0.1.1

Initial release of the _Delete User Data_ extension.

Où ce contenu s'affiche-t-il pour l'utilisateur ?

• Dans la console Firebase et la CLI, lorsque les utilisateurs passent à de nouvelles versions de votre extension. La console Firebase et la CLI n'affichent que les modifications qui prendraient effet si l'utilisateur effectuait la mise à niveau.
• Dépôt du code source de votre extension (dans le répertoire de l'extension).