Jede Erweiterung muss über eine Dokumentation verfügen, die den Benutzern erklärt, was die Erweiterung bewirkt und wie sie verwendet wird.
Die erforderliche Mindestdokumentation besteht aus diesem Satz von drei Markdown-Dateien:
-
PREINSTALL.md
-
POSTINSTALL.md
-
CHANGELOG.md
Darüber hinaus sollten Sie Folgendes in Betracht ziehen:
- Eine
README
-Datei für das öffentliche Repository der Erweiterung. - Längere Tutorials, Leitfäden und Referenzen werden auf Ihrer eigenen Website veröffentlicht und in Ihrer
PREINSTALL.md
verlinkt.
Um einige Best Practices sowie gängige Formulierungen und Strukturen kennenzulernen, empfehlen wir einen Blick auf die mit den offiziellen Firebase-Erweiterungen verfügbaren Dateien.
Erstellen einer README-Datei
Ihr Erweiterungsverzeichnis kann optional eine README-Datei enthalten. Beachten Sie, dass der firebase ext:dev:init
nicht automatisch einen generiert.
Die Firebase-CLI unterstützt jedoch den folgenden praktischen Befehl zum automatischen Generieren einer README
Datei mit Inhalten, die aus Ihrer Datei extension.yaml
und Ihrer Datei PREINSTALL.md
abgerufen wurden:
firebase ext:info ./path/to/extension --markdown > README.md
Mit diesem Befehl werden alle README-Dateien für die offiziellen Firebase-Erweiterungen generiert.
Fügen Sie Installationsinformationen hinzu
Nachdem Sie eine README-Datei geschrieben oder generiert haben, fügen Sie ihr Installationsinformationen hinzu. Sie können den folgenden Ausschnitt als Vorlage verwenden:
--- ## 🧩 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) ---
Schreiben einer PREINSTALL
Datei
Die PREINSTALL
Datei ist die Übersicht Ihrer Erweiterung, eine Art „Marketing“-Seite.
Welchen Inhalt enthält diese Datei?
- Umfassende Beschreibung der Funktionalität Ihrer Erweiterung
- Liste der Voraussetzungen, z. B. Datenbankeinrichtung oder Zugriff auf einen Nicht-Google-Dienst ( Beispiel )
- Kurze Beschreibung aller Vorinstallationsaufgaben und deren Anweisungen
- Kurze Beschreibung aller Aufgaben nach der Installation ( Beispiel ) (ausführliche Anweisungen finden Sie in
POSTINSTALL
) - Kurze Beschreibung aller Auswirkungen auf die Abrechnung (beginnen Sie mit dem Standardtext )
Wo wird dieser Inhalt dem Benutzer angezeigt?
![Bild des vorinstallierten Inhalts in der Firebase-Konsole](https://cdn.statically.io/img/firebase.google.com/static/docs/extensions/publishers/images/preinstall_thumb.png?hl=de)
- Auf der Seite der Erweiterung auf extensions.dev .
- Ihr Quellcode-Repo für Ihre Erweiterung (im Erweiterungsverzeichnis)
- Als Teil der README-Datei der Erweiterung (wenn Sie die Firebase-CLI verwenden
--markdown > README.md
Flag)
PREINSTALL
Dateien können nicht auf die Parameterwerte für die Erweiterung zugreifen, daher sollten Sie nicht erwarten, dass Parameterverweise mit tatsächlichen Werten gerendert werden.
Was sind einige Best Practices?
Beschränken Sie den gesamten Inhalt der PREINSTALL
Datei nach Möglichkeit auf weniger als eine SeiteGeben Sie den Detaillierungsgrad an, den ein Endbenutzer unbedingt wissen muss, bevor er die Erweiterung installiert Fügen Sie detaillierte Anweisungen in die POSTINSTALL
Datei oder andere Zusatzdateien einErwähnen Sie kurz, ob Sie andere Tools oder Skripte zur Unterstützung der Erweiterung bereitstellen
Schreiben einer POSTINSTALL
Datei
POSTINSTALL
DateiPOSTINSTALL
Datei ist die detaillierte Anleitungsseite Ihrer Erweiterung nach der Installation.
Welchen Inhalt enthält diese Datei?
Detaillierte Anweisungen für alle erforderlichen Aufgaben nach der Installation, wie das Einrichten von Firebase-Sicherheitsregeln oder das Hinzufügen von clientseitigem Code ( Beispiel ) Allgemeine Anweisungen zum sofortigen Ausprobieren der installierten Erweiterung (z. B. „Gehen Sie zur Konsole und führen Sie dies aus“). Grundlegende Informationen zum Auslösen der Erweiterung, insbesondere für durch HTTP-Anfragen ausgelöste Erweiterungen Kurze Anleitung zur Überwachung der installierten Erweiterung (beginnen Sie mit dem Textbaustein )
Wo wird dieser Inhalt dem Benutzer angezeigt?
![Bild des Inhalts nach der Installation in der Firebase-Konsole](https://cdn.statically.io/img/firebase.google.com/static/docs/extensions/publishers/images/postinstall_thumb.png?hl=de)
In der Firebase-Konsole, nachdem ein Benutzer Ihre Erweiterung installiert hat (in der Detailkarte der installierten Erweiterung) Überprüfen Sie unbedingt die Anzeige des POSTINSTALL
Inhalts, indem Sie Ihre Erweiterung in einem tatsächlichen Projekt installieren .
Ihr Quellcode-Repo für Ihre Erweiterung (im Erweiterungsverzeichnis)
POSTINSTALL
Dateien können auf die Parameterwerte und mehrere funktionsbezogene Variablen für die Erweiterung zugreifen. Wenn der Inhalt POSTINSTALL
in der Firebase-Konsole angezeigt wird, werden die tatsächlichen Werte und nicht die Parameter- oder Variablenverweise angezeigt. Erfahren Sie weiter unten mehr darüber, wie Sie Parameter und Variablen in Ihrer POSTINSTALL
Datei referenzieren.
Was sind einige Best Practices?
Halten Sie den gesamten Inhalt der POSTINSTALL
Datei prägnant, aber beschreibend.Unterteilen Sie den Inhalt mithilfe von Überschriften, um bestimmte Aufgaben oder Konzepte aufzuschlüsseln. Erwägen Sie die Veröffentlichung detaillierter Anweisungen für einen bestimmten Arbeitsablauf oder eine bestimmte Aufgabe auf Ihrer Website ( Beispiel ) oder in zusätzlichen Markdown-Dateien im Erweiterungs-Repository ( Beispiel ). Referenzieren Sie Parameter und funktionsbezogene Variablen , damit der Benutzer ihre konfigurierten Werte im Kontext der Anweisungen sieht
Referenzieren von Parametern und Variablen
POSTINSTALL
Datei der Erweiterung an. Wenn Sie in Ihrer POSTINSTALL
Datei auf Parameter und funktionsbezogene Variablen verweisen (siehe Tabelle unten), füllt die Konsole diese Verweise mit den tatsächlichen Werten für die installierte Instanz.
POSTINSTALL
Datei zu:${param: PARAMETER_NAME }
POSTINSTALL
Datei referenzieren. Firebase unterstützt diese Variablen, sodass Sie Ihren Benutzern nach der Installation einfacher Anleitungen geben können. Sie können nur in der Datei POSTINSTALL
verwendet werden, da die Werte für diese Variablen erst nach der Installation verfügbar sind.
name
im Ressourcenobjekt der Funktion in extension.yaml
.
Referenz für funktionsbezogene Variable | Beschreibung | Variablenwert (wird von Firebase nach der Installation der Erweiterung automatisch ausgefüllt) |
---|---|---|
${function: function-name .location} | ||
Ort , an dem die Funktion bereitgestellt wird | Beispielwert:us-central1 | |
${function: function-name .name} | ||
Name der endgültig bereitgestellten Funktion, einschließlich der Instanz-ID der Erweiterung | Verallgemeinertes Format: Beispielwert: | |
${function: function-name .url} (gilt nur für HTTP-Funktionen) | ||
URL der endgültig bereitgestellten Funktion, an die der Clientcode HTTP-Anfragen stellen kann | Verallgemeinertes Format: Beispielwert: |
Dokumentieren, wie eine Verlängerung ausgelöst wird
POSTINSTALL
Datei . Um eine Anleitung zur Bereitstellung dieser Anweisungen zu erhalten, erweitern Sie den Abschnitt unten, der für Ihre Erweiterung gilt.
Schreiben einer CHANGELOG-Datei
Welchen Inhalt enthält diese Datei?
CHANGELOG.md
Datei verfügen, die die Änderungen dokumentiert, die in jeder neuen Version Ihrer von Ihnen veröffentlichten Erweiterung enthalten sind. Platzieren Sie jede Version unter einem Level-2-Header ( ##
); Andernfalls können Sie die gewünschte Markdown-Formatierung verwenden.
## 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.
Wo wird dieser Inhalt dem Benutzer angezeigt?
In der Firebase-Konsole und CLI, wenn Benutzer auf neue Versionen Ihrer Erweiterung aktualisieren. Die Firebase-Konsole und die CLI zeigen nur die Änderungen an, die wirksam würden, wenn der Benutzer das Upgrade abschließen würde. Das Quellcode-Repository Ihrer Erweiterung (im Erweiterungsverzeichnis).