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

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

Minimalna wymagana dokumentacja to zestaw 3 plików Markdown:

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

Warto też rozważyć produkcję:

• Plik README dla publicznego repozytorium rozszerzenia.
• dłuższe samouczki, przewodniki i materiały referencyjne opublikowane w Twojej witrynie i powiązane z nią przez link w sekcji PREINSTALL.md.

Aby poznać sprawdzone metody oraz typowe sformułowania i struktury, 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 komenda firebase ext:dev:init nie generuje automatycznie pliku.

Interfejs wiersza poleceń Firebase obsługuje jednak to wygodne polecenie, które automatycznie generuje plik README zawierający treści z pliku extension.yaml i pliku PREINSTALL.md:

firebase ext:info ./path/to/extension --markdown > README.md

Wszystkie pliki README dla oficjalnych rozszerzeń Firebase 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 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ń przedinstalacyjnych i ich instrukcje
• Krótki opis zadań wykonywanych po instalacji (przykład). Szczegółowe instrukcje znajdziesz w artykule POSTINSTALL.
• Krótki opis wszelkich konsekwencji rozliczeniowych (zacznij od tekstu standardowego).

Gdzie te treści są wyświetlane użytkownikowi?

Konsola Firebase">

Konsola Firebase">

• Na stronie rozszerzenia na stronie extensions.dev.
• repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia);
• W ramach pliku README rozszerzenia (jeśli używasz wiersza poleceń Firebase --markdown > README.md flag)

Pliki PREINSTALL nie mają dostępu do wartości parametrów rozszerzenia, więc nie należy się spodziewać, że odwołania do parametrów będą renderowane z rzeczywistymi wartościami.

Jakie są sprawdzone metody?

• Jeśli to możliwe, ogranicz zawartość pliku PREINSTALL do mniej niż jednej strony.
• Podaj poziom szczegółowości, który użytkownik końcowy musi znać przed zainstalowaniem rozszerzenia.
• Dodaj szczegółowe instrukcje w pliku POSTINSTALL lub innych plikach dodatkowych.
• Krótko wspomnij, czy udostępniasz inne narzędzia lub skrypty do obsługi rozszerzenia.

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 instruktażowa rozszerzenia po zainstalowaniu.

Jakie treści zawiera ten plik?

• Szczegółowe instrukcje dotyczące wszystkich wymaganych zadań po instalacji, takich jak konfigurowanie reguł zabezpieczeń Firebase czy dodawanie kodu po stronie klienta (przykład).
• ogólne instrukcje dotyczące natychmiastowego wypróbowania zainstalowanego rozszerzenia (np. „wejdź do konsoli, a potem wykonaj tę czynność”);
• podstawowe informacje o tym, jak aktywować rozszerzenie, zwłaszcza w przypadku rozszerzeń aktywowanych żądaniem HTTP;
• Krótkie wskazówki dotyczące monitorowania zainstalowanego rozszerzenia (zacznij od tekstu standardowego).

Gdzie te treści są wyświetlane użytkownikowi?

Konsola Firebase">

Konsola Firebase">

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

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

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

POSTINSTALL pliki mają dostęp do wartości parametrów i kilku zmiennych funkcji rozszerzenia. Gdy treść POSTINSTALL jest wyświetlana w konsoli Firebase, zamiast odwołań do parametrów lub zmiennych 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?

• Plik POSTINSTALL powinien zawierać zwięzłą, ale wyczerpująco opisową treść.
• Podziel treści na sekcje za pomocą nagłówków, aby oddzielić od siebie poszczególne zadania lub pojęcia.
• Zastanów się nad opublikowaniem szczegółowych instrukcji dotyczących konkretnego procesu lub zadania na swojej stronie internetowej (przykład) lub w dodatkowych plikach Markdown w repozytorium rozszerzeń (przykład).
• odwoływać się do parametrów i zmiennych powiązanych z funkcją, aby użytkownik widział skonfigurowane wartości w kontekście instrukcji;

Odwoływanie się do parametrów i zmiennych

Po zainstalowaniu 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 zainstalowanego wystąpienia.

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 funkcją tylko w pliku POSTINSTALL. Firebase obsługuje te zmienne, aby ułatwić użytkownikom korzystanie z aplikacji po jej zainstalowaniu. 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 elementach 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 aktywowania rozszerzenia

W dokumentacji rozszerzenia musisz poinformować użytkowników, jak je aktywować. Te instrukcje mogą być tak szczegółowe, jak uznasz to za konieczne, ale pamiętaj o sprawdzonym sposobie tworzenia pliku POSTINSTALL. Aby dowiedzieć się, jak to zrobić, 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. Umieść każdą wersję pod nagłówkiem poziomu 2 (##). W innych przypadkach możesz użyć dowolnego formatowania Markdown.

Poniżej znajdziesz 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 w interfejsie wiersza poleceń, gdy użytkownicy uaktualnią rozszerzenie do nowej wersji. Konsola Firebase i interfejs wiersza poleceń wyświetlają tylko zmiany, które wejdą w życie, jeśli użytkownik przeprowadzi uaktualnienie.
• repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia).