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 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ę, a potem zrób to”).
• 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, dzięki czemu możesz łatwiej przekazywać użytkownikom wskazówki 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 pisania pliku.POSTINSTALL Wskazówki dotyczące podawania tych instrukcji znajdziesz w sekcji 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).