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

Każde rozszerzenie musi mieć dokumentację z informacjami dla użytkowników i jak z nich korzystać.

Wymagana dokumentacja to co najmniej 3 pliki Markdown:

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

Dodatkowo warto też zadbać o produkty:

• Plik README publicznego repozytorium rozszerzenia.
• Dłuższe samouczki, przewodniki i materiały referencyjne opublikowane na własnej stronie internetowej połączone w PREINSTALL.md.

Aby poznać sprawdzone metody oraz typowe sformułowania i strukturę, zalecamy przeglądać pliki dostępne oficjalnych rozszerzeń do Firebase.

Tworzenie pliku README

Katalog rozszerzenia może opcjonalnie zawierać plik README. Pamiętaj, że parametr Polecenie firebase ext:dev:init nie generuje go automatycznie.

Interfejs wiersza poleceń Firebase obsługuje jednak poniższe wygodne polecenie, aby automatycznie wygeneruj plik README zawierający treści pobrane z Twojego extension.yaml i Twój plik PREINSTALL.md:

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

Wszystkie pliki README dla oficjalne rozszerzenia do aplikacji Firebase generowane za pomocą tego polecenia.

Dodaj informacje o instalacji

Po napisaniu lub wygenerowaniu pliku README dodaj do niego informacje o instalacji. Ty Możesz użyć tego fragmentu jako szablonu:

---

## 🧩 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 streszczenie rozszerzenia, typ „marketingowy” stronę.

Jaką zawartość zawiera ten plik?

• Wyczerpujący opis funkcji rozszerzenia
• Lista wymagań wstępnych, takich jak konfiguracja bazy danych lub dostęp do usługa (przykład)
• Krótki opis zadań preinstalacyjnych i ich instrukcje
• Krótki opis zadań po instalacji (przykład) (szczegółowe instrukcje znajdziesz w POSTINSTALL)
• Krótki opis wpływu na płatności (zaczyna się od tekst stały)

Gdzie użytkownik zobaczy te treści?

Konsola Firebase">

Konsola Firebase">

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

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 rzeczywistymi wartościami.

Jakie są sprawdzone metody?

• Całą zawartość pliku PREINSTALL umieść na jednej stronie, jeśli to możliwe
• Podaj poziom szczegółowości, który musi znać użytkownik zanim zainstalujesz rozszerzenie.
• Umieść szczegółowe instrukcje w pliku POSTINSTALL lub w innym pliki dodatkowe
• Krótko wspomnij, czy udostępniasz inne narzędzia lub skrypty do obsługi 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ółowe dane rozszerzenia po instalacji z instrukcjami.

Jaką zawartość zawiera ten plik?

• szczegółowe instrukcje dotyczące wymaganych zadań po instalacji; np. przez skonfigurowanie reguł zabezpieczeń Firebase lub dodanie kodu po stronie klienta. (przykład)
• Ogólne instrukcje dotyczące natychmiastowego testowania zainstalowane rozszerzenie (na przykład „otwórz konsolę, a następnie wykonaj to działanie”)
• Podstawowe informacje o tym, jak aktywować rozszerzenie, zwłaszcza w przypadku: Rozszerzenia wywoływane przez żądania HTTP
• Krótkie instrukcje monitorowania zainstalowanego rozszerzenia (zaczynając od tekst stały)

Gdzie użytkownik zobaczy te treści?

Konsola Firebase">

Konsola Firebase">

• Gdy użytkownik zainstaluje rozszerzenie w konsoli Firebase (w sekcji karty szczegółów zainstalowanego rozszerzenia).

  • Sprawdź wyświetlanie treści POSTINSTALL do zainstalowanie rozszerzenia w projektu.

• Repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzeń)

Pliki POSTINSTALL mają dostęp do wartości parametrów i kilku funkcji związanych z funkcjami zmiennych dla rozszerzenia. Gdy treść POSTINSTALL jest wyświetlana w w konsoli Firebase wyświetlają się rzeczywiste wartości, a nie parametr lub odwołania do zmiennych. Dowiedz się więcej poniżej o tym, jak odwoływać się do parametrów w pliku POSTINSTALL.

Jakie są sprawdzone metody?

• Pełna treść pliku POSTINSTALL powinna być zwięzła, ale opisowa.
• Podziel treści na sekcje za pomocą nagłówków, aby rozdzielić zadania lub zadania. i koncepcjach.
• Rozważ opublikowanie szczegółowych instrukcji przepływ pracy lub zadanie w Twojej witrynie (przykład) lub w dodatkowych plikach Markdown w repozytorium rozszerzeń (przykład).
• Parametry odwołania i związane z funkcjami zmienne tak aby użytkownik widział swoje skonfigurowane wartości w kontekście instrukcji

Parametry i zmienne odwołania

Po instalacji w konsoli Firebase wyświetli się zawartość pliku POSTINSTALL rozszerzenia. Jeśli odwołasz się do parametrów i funkcji związanych zmiennych (patrz tabela poniżej) w pliku POSTINSTALL, a następnie uzupełnia te odwołania wartościami rzeczywistymi dotyczącymi zainstalowanej instancji.

Uzyskaj dostęp do skonfigurowanych wartości parametrów w pliku POSTINSTALL za pomocą ta składnia: ${param:PARAMETER_NAME}

Możesz także odwołać się do następujących zmiennych związanych z funkcjami w POSTINSTALL tylko dla pliku. Firebase obsługuje te zmienne, dzięki czemu możesz ułatwienie użytkownikom przekazywania wskazówek po instalacji. Są to tylko do użycia w pliku POSTINSTALL, ponieważ wartości tych zmiennych są dostępne dopiero po instalacji.

W tej tabeli function-name to wartość atrybutu name w polu obiektu zasobu funkcji w ciągu 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 użytkownika rozszerzenia musisz poinformować użytkowników o tym, jak uruchomić rozszerzenie. Te instrukcje mogą być bardzo szczegółowe ale pamiętaj o sprawdzonych metodach tworzenia POSTINSTALL. Aby uzyskać wskazówki dotyczące przekazywania tych instrukcji, rozwiń sekcję poniżej dotyczy Twojego rozszerzenia.

Zapisywanie pliku CHANGELOG

Jaką zawartość zawiera ten plik?

Każde rozszerzenie musi mieć plik CHANGELOG.md zawierający dokumenty dotyczące zmian dołączana do każdej nowej wersji opublikowanego przez Ciebie rozszerzenia. Umieść każdą wersję pod nagłówkiem poziomu 2 (##); W przeciwnym razie użyj dowolnego formatu Markdown zgodnie z Twoim preferowanym formatem.

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 użytkownik zobaczy te treści?

• W konsoli i interfejsie wiersza poleceń Firebase, gdy użytkownicy przejdą na nowe wersje . Konsola Firebase i interfejs wiersza poleceń wyświetlają tylko te zmiany, które zacznie obowiązywać, jeśli użytkownik dokończy uaktualnienie.
• Repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzeń).