Utwórz dokumentację użytkownika dotyczącą rozszerzenia

Każde rozszerzenie musi mieć dokumentację, która wyjaśnia użytkownikom, do czego służy i jak z niego korzystać.

Minimalna wymagana dokumentacja to te 3 pliki Markdown:

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

Warto też rozważyć utworzenie:

• plik README dla publicznego repozytorium rozszerzenia;
• Dłuższe samouczki, przewodniki i materiały referencyjne opublikowane w Twojej witrynie i połączone linkami w PREINSTALL.md.

Aby poznać sprawdzone metody oraz typowe sformułowania i struktury, zalecamy zapoznanie się z plikami dostępnymi w ramach oficjalnych Firebase rozszerzeń.

Tworzenie pliku README

Katalog rozszerzenia może opcjonalnie zawierać plik README. Pamiętaj, że polecenie firebase ext:dev:init nie generuje automatycznie takiego pliku.

Interfejs Firebase obsługuje jednak to wygodne polecenie, które automatycznie generuje plik README zawierający treści pobrane z pliku extension.yaml i pliku 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 szablonu możesz użyć tego fragmentu kodu:

---

## 🧩 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)

---

Zapisywanie pliku PREINSTALL

Plik PREINSTALL to przegląd rozszerzenia, czyli rodzaj strony „marketingowej”.

Jakie treści zawiera ten plik?

• Szczegółowy opis funkcji rozszerzenia
• Lista wymagań wstępnych, takich jak konfiguracja bazy danych lub dostęp do usługi innej niż Google (przykład).
• Krótki opis zadań przed instalacją i instrukcje dotyczące ich wykonania
• Krótki opis zadań po instalacji (przykład) (szczegółowe instrukcje znajdziesz w POSTINSTALL)
• Krótki opis wszelkich konsekwencji związanych z płatnościami (zacznij od tekstu standardowego).

Gdzie te treści wyświetlają się użytkownikowi?

konsoli Firebase

Konsola Firebase">

• Na stronie rozszerzenia na extensions.dev.
• repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia);
• w ramach 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 należy oczekiwać, że odwołania do parametrów będą renderowane z użyciem rzeczywistych wartości.

Jakie są sprawdzone metody?

• Jeśli to możliwe, umieść całą zawartość pliku PREINSTALL na jednej stronie.
• Podaj poziom szczegółowości, który jest niezbędny dla użytkownika końcowego przed zainstalowaniem rozszerzenia.
• Umieść szczegółowe instrukcje w pliku POSTINSTALL lub innych plikach dodatkowych.
• Krótko wspomnij, czy udostępniasz inne narzędzia lub skrypty, które obsługują rozszerzenie.

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>.

Zapisywanie pliku POSTINSTALL

Plik POSTINSTALL to szczegółowa strona z instrukcjami po instalacji rozszerzenia.

Jakie treści zawiera ten plik?

• Szczegółowe instrukcje dotyczące wszystkich wymaganych czynności 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ę, a potem wykonaj te czynności”).
• Podstawowe informacje o tym, jak uruchomić rozszerzenie, zwłaszcza w przypadku rozszerzeń uruchamianych przez żądanie HTTP.
• Krótkie instrukcje monitorowania zainstalowanego rozszerzenia (zacznij od tekstu standardowego)

Gdzie te treści wyświetlają się użytkownikowi?

Konsola Firebase

Konsola Firebase">

• w Firebase po zainstalowaniu rozszerzenia przez użytkownika (na karcie szczegółów zainstalowanego rozszerzenia);

  • Sprawdź wyświetlanie POSTINSTALL treści, instalując rozszerzenie w rzeczywistym projekcie.

• repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia);

Pliki POSTINSTALL mogą uzyskiwać dostęp do wartości parametrów i kilku zmiennych związanych z funkcjami rozszerzenia. Gdy w konsoli Firebase wyświetlana jest treść POSTINSTALL, zamiast odwołań do parametru lub zmiennej wyświetlane są rzeczywiste wartości. Poniżej znajdziesz więcej informacji o tym, jak odwoływać się do parametrów i zmiennych w pliku POSTINSTALL.

Jakie są sprawdzone metody?

• Zachowaj zwięzłość, ale dodaj opis pełnej zawartości pliku POSTINSTALL.
• Podziel treść na sekcje za pomocą nagłówków, aby rozdzielić poszczególne zadania lub koncepcje.
• Rozważ opublikowanie szczegółowych instrukcji dotyczących konkretnego przepływu pracy lub zadania na swojej stronie internetowej (przykład) lub w dodatkowych plikach Markdown w repozytorium rozszerzenia (przykład).
• Odwołuj się do parametrów i zmiennych związanych z funkcjami tak, aby użytkownik widział skonfigurowane przez siebie wartości w kontekście instrukcji.

Odwoływanie się do parametrów i zmiennych

Po zainstalowaniu w konsoli Firebase wyświetli się 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 dla zainstalowanej instancji.

Uzyskaj dostęp do skonfigurowanych wartości parametru w pliku POSTINSTALL, używając 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 ramach 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.

Dokumentowanie sposobu wywoływania rozszerzenia

W dokumentacji użytkownika rozszerzenia musisz podać instrukcje, jak uruchomić rozszerzenie. Instrukcje mogą być tak szczegółowe, jak uważasz za konieczne, ale pamiętaj o sprawdzonych metodach tworzenia pliku POSTINSTALL. Aby dowiedzieć się, jak przekazać te instrukcje, 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 (##). Możesz też użyć dowolnego formatowania Markdown.

Poniższy 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 wyświetlają się użytkownikowi?

• W Firebase konsoli i CLI, gdy użytkownicy przechodzą na nowe wersje Twojego rozszerzenia. Konsola Firebase i interfejs CLI wyświetlają tylko zmiany, które zostałyby wprowadzone, gdyby użytkownik dokończył uaktualnianie.
• Repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia).