Każde rozszerzenie musi mieć dokumentację, która informuje użytkowników o tym, co robi rozszerzenie i jak go używać.
Minimalna wymagana dokumentacja to ten zestaw 3 plików Markdown:
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.md
Oprócz tego warto też przygotować:
- plik
READMEw publicznym repozytorium rozszerzenia; - dłuższe samouczki, przewodniki i materiały referencyjne opublikowane w Twojej witrynie i połączone z plikiem
PREINSTALL.md.
Aby poznać sprawdzone metody oraz typowe sformułowania i strukturę, zalecamy zapoznanie się z plikami dostępnymi w oficjalnych rozszerzeniach.Firebase
Tworzenie pliku README
Katalog rozszerzenia może opcjonalnie zawierać plik README. Pamiętaj, że polecenie firebase ext:dev:init nie generuje go automatycznie.
Interfejs wiersza poleceń Firebase obsługuje jednak to wygodne polecenie, które
automatycznie generuje plik README zawierający treści pobrane z plików
extension.yaml i PREINSTALL.md:
firebase ext:info ./path/to/extension --markdown > README.md
Wszystkie pliki README dla oficjalnych Firebase rozszerzeń są generowane za pomocą tego polecenia.
Dodawanie informacji o instalacji
Po napisaniu lub wygenerowaniu pliku README dodaj do niego informacje o instalacji. Jako szablon możesz użyć tego fragmentu kodu:
--- ## 🧩 Install this extension ### Console [][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) ---
Tworzenie pliku PREINSTALL
Plik PREINSTALL to omówienie rozszerzenia, czyli rodzaj strony „marketingowej”.
Jakie treści zawiera ten plik?
- Wyjaśnienie funkcji rozszerzenia
- Lista wymagań wstępnych, takich jak konfiguracja bazy danych lub dostęp do usługi innej niż Google service (przykład)
- Krótki opis zadań przed instalacją i instrukcje ich wykonania
- Krótki opis zadań po instalacji
(przykład)
(szczegółowe instrukcje znajdziesz w pliku
POSTINSTALL) - Krótki opis konsekwencji związanych z rozliczeniami (zacznij od tekstu schematycznego)
Gdzie te treści są wyświetlane użytkownikowi?
konsola Firebase">
Firebase console">
- Na stronie rozszerzenia w extensions.dev.
- W repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia).
- W pliku README rozszerzenia (jeśli używasz flagi Firebase CLI
--markdown > README.md
Pliki PREINSTALL nie mają dostępu do wartości parametrów rozszerzenia, więc nie oczekuj, że odwołania do parametrów będą renderowane z rzeczywistymi wartościami.
Jakie są sprawdzone metody postępowania w takiej sytuacji?
- Jeśli to możliwe, zadbaj, aby cała zawartość pliku
PREINSTALLmieściła się na jednej stronie, - Podaj poziom szczegółowości, który jest niezbędny użytkownikowi przed zainstalowaniem rozszerzenia.
- Szczegółowe instrukcje umieść w pliku
POSTINSTALLlub innych plikach dodatkowych. - Krótko wspomnij, czy udostępniasz inne narzędzia lub skrypty obsługujące rozszerzenie.
Tworzenie pliku POSTINSTALL
Plik POSTINSTALL to szczegółowa strona z instrukcjami po instalacji rozszerzenia.
Jakie treści zawiera ten plik?
- Szczegółowe instrukcje dotyczące wymaganych zadań po instalacji, takich jak konfigurowanie reguł zabezpieczeń Firebase lub dodawanie kodu po stronie klienta (przykład)
- Ogólne instrukcje dotyczące natychmiastowego wypróbowania zainstalowanego rozszerzenia (np. „Otwórz konsolę i wykonaj te czynności”).
- Podstawowe informacje o tym, jak aktywować rozszerzenie, zwłaszcza w przypadku rozszerzeń aktywowanych przez żądanie HTTP.
- Krótkie instrukcje dotyczące monitorowania zainstalowanego rozszerzenia (zacznij od tekstu schematycznego).
Gdzie te treści są wyświetlane użytkownikowi?
konsola Firebase">
Firebase console">
W konsoli Firebase po zainstalowaniu rozszerzenia przez użytkownika (na karcie szczegółów zainstalowanego rozszerzenia).
W repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia).
Pliki POSTINSTALL mają dostęp do wartości parametrów i kilku zmiennych związanych z funkcjami rozszerzenia. Gdy treści POSTINSTALL są wyświetlane w
konsoli Firebase, zamiast odwołań do parametrów
lub zmiennych wyświetlane są rzeczywiste wartości. Więcej informacji o tym, jak odwoływać się do parametrów i
zmiennych w pliku POSTINSTALL, znajdziesz poniżej.
Jakie są sprawdzone metody postępowania w takiej sytuacji?
- Zadbaj, aby cała zawartość pliku
POSTINSTALLbyła zwięzła, ale opisowa. - Podziel treści na sekcje za pomocą nagłówków, aby rozdzielić poszczególne zadania lub koncepcje.
- Rozważ opublikowanie szczegółowych instrukcji dotyczących konkretnego procesu lub zadania w swojej witrynie (przykład) albo w dodatkowych plikach Markdown w repozytorium rozszerzenia (przykład).
- Odwołuj się do parametrów i zmiennych związanych z funkcjami , aby użytkownik widział skonfigurowane wartości w kontekście instrukcji.
Odwoływanie się do parametrów i zmiennych
Po instalacji konsola Firebase wyświetla zawartość pliku POSTINSTALL rozszerzenia. Jeśli w pliku POSTINSTALL odwołujesz się do parametrów i zmiennych związanych z funkcjami (patrz tabela poniżej), konsola wypełnia te odwołania rzeczywistymi wartościami zainstalowanej instancji.
Aby uzyskać dostęp do skonfigurowanych wartości parametrów w pliku POSTINSTALL, użyj tej
składni: ${param:PARAMETER_NAME}
Możesz też odwoływać się do tych zmiennych związanych z funkcjami tylko w pliku
POSTINSTALL. Firebase obsługuje te zmienne, aby ułatwić Ci przekazywanie użytkownikom wskazówek po instalacji. Można ich używać tylko w pliku POSTINSTALL, ponieważ wartości tych zmiennych są dostępne dopiero po instalacji.
W tej tabeli function-name to wartość pola
name w obiekcie zasobu funkcji w pliku extension.yaml.
| Odwołanie do zmiennej związanej z funkcją | Opis | Wartość zmiennej (wypełniana automatycznie przez Firebase po zainstalowaniu rozszerzenia) |
|---|---|---|
${function:function-name.location}
|
||
| Lokalizacja w której wdrożono funkcję. |
Przykładowa wartość:us-central1
|
|
${function:function-name.name}
|
||
| Nazwa ostatecznej wdrożonej funkcji, która zawiera identyfikator instancji rozszerzenia. |
Uogólniony format:
Przykładowa wartość: |
|
${function:function-name.url}
(dotyczy tylko funkcji HTTP)
|
||
| Adres URL ostatecznej wdrożonej funkcji, do której kod klienta może wysyłać żądania HTTP. |
Uogólniony format:
Przykładowa wartość: |
|
Dokumentowanie sposobu aktywowania rozszerzenia
W dokumentacji użytkownika rozszerzenia musisz poinstruować użytkowników, jak aktywować rozszerzenie. Instrukcje mogą być tak szczegółowe, jak u
ważasz za konieczne, ale pamiętaj o sprawdzonych metodach tworzenia
POSTINSTALL pliku.
Aby uzyskać wskazówki dotyczące tworzenia tych instrukcji, rozwiń sekcję poniżej, która dotyczy Twojego rozszerzenia.
Tworzenie pliku CHANGELOG
Jakie treści zawiera ten plik?
Każde rozszerzenie musi mieć plik CHANGELOG.md, który dokumentuje zmiany wprowadzone w każdej nowej wersji rozszerzenia. Każdą wersję umieść pod nagłówkiem poziomu 2 (##). W przeciwnym razie możesz użyć dowolnego formatowania Markdown.
Ten przykład to fragment jednego z oficjalnych rozszerzeń:
## 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.
Gdzie te treści są wyświetlane użytkownikowi?
- W konsoli Firebase i interfejsie wiersza poleceń, gdy użytkownicy uaktualniają rozszerzenie do nowych wersji. Konsola Firebase i interfejs wiersza poleceń wyświetlają tylko zmiany, które zostaną wprowadzone, jeśli użytkownik dokończy uaktualnienie.
- W repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia).