Publier votre extension

Cette page explique comment publier une extension sur le Hub des extensions.

Avant de commencer

Pour publier une extension, vous devez d'abord vous enregistrer en tant qu'éditeur d'extensions.

Sources vérifiables

Toutes les extensions publiées sur le Hub des extensions doivent disposer d'une source vérifiable publiquement. Au lieu d'importer directement le code source de votre extension dans le Hub des extensions, vous spécifiez l'emplacement de la source. Le Hub des extensions le télécharge et le compile à partir de cet emplacement.

Actuellement, cela signifie que vous devez rendre le code source de votre extension disponible dans un dépôt GitHub public.

L'importation à partir d'une source vérifiable présente plusieurs avantages :

  • Les utilisateurs peuvent inspecter le code source de la révision spécifique de l'extension qui sera installée.
  • Vous pouvez vous assurer que vous n'importez que ce que vous avez l'intention d'importer, et non, par exemple, des travaux en cours ou des fichiers perdus provenant du développement.

Cycle de développement recommandé

Les outils de développement Firebase Extensions permettent d'importer des versions préliminaires de vos extensions. Vous pouvez ainsi facilement tester vos extensions et le processus d'installation des extensions dans le même environnement dans lequel elles seront finalement publiées.

Cette fonctionnalité permet un cycle de développement comme celui-ci :

  1. Développez votre extension et itérez rapidement dessus à l'aide de la suite d'émulateurs Firebase.

  2. Testez votre extension dans un projet réel en l'installant à partir d'une source locale :

    firebase ext:install /path/to/extension
firebase deploy --only extensions

  3. Importez une version préliminaire dans le Hub des extensions (voir ci-dessous). Distribuez le lien d'installation pour des tests plus larges et itérez en important d'autres versions préliminaires si nécessaire.

  4. Importez la version finale et stable dans le Hub des extensions (voir ci-dessous) et envoyez la pour examen. Si l'extension est approuvée, elle sera publiée sur le Hub des extensions.

  5. Incrémentez le numéro de version dans extension.yaml et répétez ce cycle pour la version suivante de votre extension.

Importer une nouvelle extension

Pour importer une extension pour la première fois :

  1. Facultatif : Validez votre code dans un dépôt GitHub public.

  2. Exécutez la commande ext:dev:upload de la CLI Firebase :

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Source locale

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

    Dans l'appel de votre commande, vous spécifiez les éléments suivants :

    • L'ID d'éditeur que vous avez enregistré.

    • Une chaîne d'ID qui identifiera l'extension. Nommez vos extensions au format suivant : firebase-product-description-of-tasks-performed. Par exemple : firestore-bigquery-export

    La commande vous demandera des informations supplémentaires :

    • Si vous importez à partir de GitHub :

      • L'URL du dépôt de l'extension dans GitHub. Notez qu'un dépôt peut contenir plusieurs extensions, à condition que chacune d'elles ait une racine unique.

        Lorsque vous importez une nouvelle extension pour la première fois, le dépôt sera enregistré comme source canonique de votre extension.

      • Le répertoire du dépôt contenant votre extension.

      • La référence Git du commit à partir duquel vous souhaitez créer la source de la version de votre extension. Il peut s'agir d'un hachage de commit, d'un tag ou d'un nom de branche.

    • L'étape de publication de la version que vous importez.

      Les étapes alpha, beta, et rc (version candidate) permettent d'importer des versions préliminaires que les testeurs peuvent installer. Utilisez l'une de ces étapes pour l'importation initiale d'une nouvelle extension.

      L'étape stable est utilisée pour les versions publiques à publier sur le Hub des extensions. L'importation d'une version stable lance automatiquement un examen et, si elle est approuvée, publie l'extension.

    Notez que vous ne spécifiez pas de numéro de version. Cette valeur provient du extension.yaml fichier. Lorsque vous importez une version préliminaire d'une extension, l' étape et le numéro d'importation sont ajoutés à la version. Par exemple, si extension.yaml spécifie la version 1.0.1 et que vous importez une version candidate, la version 1.0.1-rc.0 est générée. L'importation d'une autre version candidate de la même version incrémente automatiquement le nombre, ce qui donne 1.0.1-rc.1, et ainsi de suite.

Maintenant que vous avez importé une version préliminaire de l'extension, vous pouvez la partager avec d'autres personnes pour qu'elles la testent. Les utilisateurs peuvent installer votre extension de deux manières :

  • Avec la console : les utilisateurs peuvent installer l'extension en cliquant sur un lien au format suivant :

    https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

    Vous pouvez partager le lien direct avec vos testeurs.

  • Avec la CLI : les utilisateurs peuvent installer l'extension en transmettant la chaîne d'ID de l'extension à la commande ext:install :

    firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id

Importer une version mise à jour

Une fois que vous avez importé la première version d'une extension, vous pouvez importer des mises à jour pour corriger des problèmes, ajouter des fonctionnalités ou faire progresser l'étape de publication. Lorsque vous importez une nouvelle version, les utilisateurs qui ont installé une version antérieure de votre extension sont invités à effectuer une mise à niveau dans la Firebase console.

Pour importer une mise à jour :

  1. Facultatif : Validez votre code dans un dépôt Git public.

  2. Exécutez la commande ext:dev:upload de la CLI Firebase :

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Cette fois, vous n'êtes pas invité à spécifier le dépôt GitHub ni le répertoire racine de l'extension, car ils ont déjà été configurés pour votre extension. Si vous avez depuis refactorisé la structure de votre dépôt ou migré vers un nouveau dépôt, vous pouvez les modifier à l'aide des arguments de commande --root et --repo.

    Source locale

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

Envoyer une extension pour publication

Lorsque vous êtes prêt à publier votre extension :

  1. Validez votre code dans un dépôt Git public. (Obligatoire pour les versions publiques.)

  2. Exécutez la commande ext:dev:upload de la CLI Firebase en spécifiant stable comme étape de publication :

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. Si vous avez déjà publié une version de votre extension, l'importation d'une nouvelle version stable envoie automatiquement l'extension pour examen.

    Si vous avez importé la première version stable de l'extension, recherchez-la dans votre tableau de bord d'éditeur, puis cliquez sur Publier sur le Hub des extensions.

Une fois l'extension envoyée, l'examen peut prendre quelques jours. Si elle est acceptée, l'extension sera publiée sur le Hub des extensions. Si elle est refusée, vous recevrez un message expliquant la raison. Vous pourrez ensuite résoudre les problèmes signalés et renvoyer l'extension pour examen.

Pour accélérer l'examen et augmenter vos chances de réussite dès la première tentative, avant d'envoyer l'extension, vérifiez les points suivants :

  • Vous avez testé minutieusement votre extension et le processus d'installation.
  • Votre documentation est complète et correcte, et s'affiche correctement dans la console Firebase.
  • Le nom et l'image de marque de votre éditeur vous identifient clairement et précisément en tant qu'éditeur.
  • Le nom, la description et l'icône de votre extension représentent clairement et précisément l'objectif de votre extension.
  • Vous avez appliqué des tags utiles et précis.
  • Vous avez déclaré dans extension.yaml toutes les API Google et non Google que vous utilisez, ainsi que tous les types d'événements émis par votre extension.
  • Vous ne demandez l'accès qu'aux rôles nécessaires au fonctionnement de l'extension, et vous avez clairement expliqué aux utilisateurs pourquoi vous avez besoin de cet accès.
  • Vos fichiers sources sont clairement concédés sous licence selon les termes de Apache-2.0.

Gérer les extensions importées et publiées

Lister vos extensions importées

Pour lister les extensions que vous avez importées sous votre ID d'éditeur, effectuez l'une des opérations suivantes :

Tableau de bord d'éditeur

Affichez-les dans le tableau de bord d'éditeur.

CLI Firebase

Exécutez la ext:dev:list commande :

firebase ext:dev:list your_publisher_id

Afficher l'utilisation de vos extensions importées

Pour afficher l'utilisation des extensions que vous avez importées sous votre ID d'éditeur, effectuez l'une des opérations suivantes :

Tableau de bord d'éditeur

Le tableau de bord d'éditeur contient des métriques d'utilisation cumulées pour toutes vos extensions et des métriques individuelles pour chaque extension.

CLI Firebase

Exécutez la commande ext:dev:usage :

firebase ext:dev:usage your_publisher_id

Rendre obsolète une version d'une extension

À un moment donné, vous pouvez rendre obsolète une ancienne version de votre extension. Par exemple, si vous publiez une nouvelle version qui corrige un bug critique ou met à jour une dépendance avec une mise à jour de sécurité importante, il est important d'empêcher les nouveaux utilisateurs d'installer une ancienne version et d'encourager les utilisateurs existants à effectuer une mise à niveau.

Pour rendre obsolète une version d'une extension, effectuez l'une des opérations suivantes :

Tableau de bord d'éditeur

  1. Dans le tableau de bord d'éditeur, cliquez sur l'extension pour ouvrir sa vue détaillée.
  2. Sélectionnez la version que vous souhaitez rendre obsolète.
  3. Cliquez sur Rendre la version obsolète.

CLI Firebase

Exécutez la commande ext:dev:deprecate :

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

Vous pouvez spécifier une seule version ou une plage de versions. Exemples :

  • 1.0.2
  • 1.1.0-1.1.7
  • <1.2.0
  • 1.1.*

Les versions obsolètes d'une extension ne sont pas listées sur le Hub des extensions et ne peuvent pas être installées. Les utilisateurs dont les projets ont installé une version obsolète verront un message les encourageant à effectuer une mise à niveau. Ils pourront toujours utiliser et reconfigurer l' extension en attendant.

Si toutes les versions d'une extension sont obsolètes, l'extension est considérée obsolète et sera supprimée du Hub des extensions. L'importation d'une nouvelle version d'une extension obsolète lance automatiquement un examen et, une fois acceptée, la publie à nouveau sur le Hub des extensions.

Pour annuler une obsolescence, utilisez le tableau de bord d'éditeur ou exécutez la commande ext:dev:undeprecate de la CLI Firebase :

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Annexe : Résoudre les erreurs de compilation

Lorsque vous importez votre extension, le backend compile d'abord votre code source à l'aide de le processus suivant :

  1. Clone votre dépôt GitHub et extrait la référence source spécifiée.

  2. Installe les dépendances NPM en exécutant npm clean-install dans chaque répertoire source de fonction spécifié dans extension.yaml (voir sourceDirectory dans les ressources Cloud Functions).

    Veuillez noter les points suivants :

    • Chaque fichier package.json doit avoir un fichier package-lock.json correspondant. Pour en savoir plus, consultez npm-ci.

    • Les scripts post-installation ne seront pas exécutés lors de l'installation des dépendances. Si la compilation de votre code source repose sur des scripts post-installation, refactorisez-le avant de l'importer.

  3. Compile votre code en exécutant npm run build dans chaque répertoire source de fonction spécifié dans extension.yaml.

Seul le répertoire racine de votre extension sera enregistré dans le package d'extension final qui sera partagé.

Si vous recevez des erreurs de compilation lors de l'importation de votre extension, reproduisez les étapes de compilation ci-dessus en local dans un nouveau répertoire jusqu'à ce qu'il n'y ait plus d'erreurs, puis réessayez d'importer.