Создайте документацию для пользователей расширения

У каждого расширения должна быть документация, в которой объясняется, что оно делает и как им пользоваться.

Минимальный набор документации состоит из трех файлов Markdown:

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

Кроме того, вы можете создавать:

• Файл README для общедоступного хранилища расширения.
• Подробные руководства, инструкции и справочные материалы, опубликованные на вашем сайте и связанные с файлом PREINSTALL.md.

Чтобы узнать о рекомендациях, а также о распространенных фразах и структурах, ознакомьтесь с файлами, доступными в официальных расширениях Firebase.

Создание файла README

Каталог расширения может содержать файл README. Обратите внимание, что команда firebase ext:dev:init не генерирует его автоматически.

Однако CLI Firebase поддерживает следующую удобную команду для автоматического создания файла README, содержащего контент, извлеченный из файлов extension.yaml и PREINSTALL.md:

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

Все файлы README для официальных расширений Firebase генерируются с помощью этой команды.

Добавьте информацию об установке

После того как вы напишете или сгенерируете файл README, добавьте в него информацию об установке. В качестве шаблона можно использовать следующий фрагмент кода:

---

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

---

Запись файла PREINSTALL

Файл PREINSTALL – это обзор расширения, своего рода маркетинговая страница.

Что содержится в этом файле?

• Подробное описание функций расширения.
• Список предварительных требований, таких как настройка базы данных или доступ к стороннему сервису (пример).
• Краткое описание задач, которые нужно выполнить перед установкой, и инструкции по их выполнению.
• Краткое описание действий, которые нужно выполнить после установки (пример). Подробные инструкции должны быть приведены в файле POSTINSTALL.
• Краткое описание последствий для оплаты (начните со стандартного текста)

Где пользователи видят этот контент?

Firebase console">

Предустановка контента в консоли Firebase

Консоль Firebase">

• На странице расширения на сайте extensions.dev.
• Хранилище исходного кода расширения (в каталоге расширения).
• В файле README расширения (если вы используете флаг --markdown > README.md интерфейса командной строки Firebase).

Файлы PREINSTALL не могут получить доступ к значениям параметров расширения, поэтому не стоит ожидать, что ссылки на параметры будут отображаться с фактическими значениями.

Какие рекомендации вы можете дать?

• По возможности ограничьте содержимое файла PREINSTALL одной страницей.
• Предоставьте информацию, которую конечный пользователь обязательно должен знать перед установкой расширения.
• Добавьте подробные инструкции в файл POSTINSTALL или другие дополнительные файлы.
• Кратко упомяните, предоставляете ли вы другие инструменты или скрипты для поддержки расширения.

Полезный шаблонный текст в тегах PREINSTALL

Рекомендуем использовать как можно больше стандартного текста, приведенного ниже, если он подходит для вашего расширения. Мы привели несколько примеров, но самое главное – указать все сервисы, за которые вы платите Google и другим компаниям.

Чтобы найти правильные сведения о ценах на товары, вы можете использовать следующие ресурсы:

• Прейскурант продуктов Google Cloud
• Обзор цен Firebase

Для всех расширений включите этот раздел, чтобы помочь пользователям понять, как работает оплата:

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

Запись файла POSTINSTALL

Файл POSTINSTALL – это страница с подробными инструкциями по установке расширения.

Что содержится в этом файле?

• Подробные инструкции по выполнению обязательных задач после установки, например по настройке правил безопасности Firebase или добавлению клиентского кода (пример).
• Общие инструкции о том, как сразу же попробовать установленное расширение (например, "перейдите в консоль и сделайте следующее").
• Базовая информация о том, как активировать расширение, особенно для расширений, активируемых HTTP-запросом.
• Краткие инструкции по отслеживанию установленного расширения (начните со стандартного текста).

Где пользователи видят этот контент?

Консоль Firebase">

Контент, доступный после установки, в консоли Firebase

Консоль Firebase">

• в консоли Firebase после того, как пользователь установит расширение (на карточке сведений об установленном расширении);

  • Проверьте, как отображается контент POSTINSTALL, установив расширение в реальный проект.

• Хранилище исходного кода расширения (в каталоге расширения).

Файлы POSTINSTALL могут получать доступ к значениям параметров и нескольким переменным, связанным с функциями расширения. Когда контент POSTINSTALL отображается в консоли Firebase, вместо ссылок на параметры или переменные показываются фактические значения. Ниже рассказывается, как указывать параметры и переменные в файле POSTINSTALL.

Какие рекомендации вы можете дать?

• Полное содержимое файла POSTINSTALL должно быть кратким, но информативным.
• Разделите контент на разделы с помощью заголовков, чтобы разбить отдельные задачи или концепции.
• Рекомендуем опубликовать подробные инструкции по определенному рабочему процессу или задаче на своем сайте (пример) или в дополнительных файлах Markdown в хранилище расширения (пример).
• Укажите параметры и переменные, связанные с функциями, чтобы пользователь видел их настроенные значения в контексте инструкций.

Как ссылаться на параметры и переменные

После установки в консоли Firebase появится содержимое файла POSTINSTALL расширения. Если в файле POSTINSTALL вы ссылаетесь на параметры и переменные, связанные с функциями (см. таблицу ниже), то консоль заполняет эти ссылки фактическими значениями для установленного экземпляра.

Совет. Если значение может быть длинным (например, путь к базе данных или URL функции), ссылайтесь на параметр или переменную в конце предложений и разделов. Это упрощает чтение предложений в консоли Firebase, когда содержимое файла POSTINSTALL отображается с фактическими значениями.

Получите доступ к настроенным значениям параметров в файле POSTINSTALL, используя следующий синтаксис: ${param:PARAMETER_NAME}.

Вы также можете ссылаться на следующие переменные, связанные с функциями, только в файле POSTINSTALL. Firebase поддерживает эти переменные, чтобы вы могли легко предоставлять пользователям инструкции после установки. Их можно использовать только в файле POSTINSTALL, поскольку значения этих переменных доступны только после установки.

В этой таблице function-name – это значение поля name в объекте ресурса функции в extension.yaml.

Справка по переменным, связанным с функциями	Описание	Значение переменной (автоматически заполняется Firebase после установки расширения)
${function:function-name.location}
	Местоположение, где развернута функция.	Пример значения: us-central1
${function:function-name.name}
	Название конечной развернутой функции, которое включает идентификатор экземпляра расширения.	Общий формат: ext-extension-instance-id-function-name Пример значения: ext-my-awesome-extension-6m31-yourFunctionName
${function:function-name.url} (только для HTTP-функций)
	URL конечной развернутой функции, к которой клиентский код может отправлять HTTP-запросы.	Общий формат: https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function Пример значения: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Полезный шаблонный текст в тегах POSTINSTALL

Рекомендуем использовать как можно больше стандартного текста, приведенного ниже, если он подходит для вашего расширения.

Для всех расширений добавьте следующий раздел, чтобы помочь пользователям отслеживать установленные расширения:

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.

Документирование способов запуска расширения

В пользовательской документации к расширению необходимо объяснить, как его запустить. Инструкции могут быть настолько подробными, насколько вы считаете нужным, но не забывайте о рекомендациях по созданию файла POSTINSTALL. Чтобы узнать, как предоставить эти инструкции, разверните раздел ниже, который относится к вашему расширению.

Расширения, активируемые фоновыми событиями

Пользователи могут активировать расширение, запускаемое фоновым событием, разными способами в зависимости от задействованных продуктов.

Внесите изменения непосредственно в консоли.

Вы можете попросить пользователей вносить изменения, запускающие расширение, непосредственно в консоли Firebase, особенно при первоначальном тестировании расширения. Например, расширение может создавать новый документ Cloud Firestore при создании нового пользователя Firebase Authentication. Вы можете попросить пользователей протестировать установленный экземпляр расширения, вручную добавив нового пользователя Authentication в консоли. Затем они могут посмотреть новый документ, созданный в разделе Cloud Firestore консоли.

Добавьте клиентский код

При необходимости вы также можете объяснить пользователям, как добавить клиентский код, чтобы активировать расширение. Вы должны направлять пользователей к официальной документации по API, которые им нужно использовать. Вы также можете включить примеры приложений или скомпилированные примеры клиентов, чтобы помочь пользователям интегрировать расширение в свое приложение (см. пример расширения Distributed Counter).

Расширения, активируемые HTTP-запросами

Чтобы пользователи могли запускать функцию, активируемую HTTP-запросом (и, следовательно, расширение), вам необходимо предоставить им название или URL-адрес развернутой функции.

Название развернутой функции не совпадает с названием name, которое вы указали в объекте ресурса функции в файле extension.yaml. Чтобы в проекте можно было установить несколько экземпляров одного расширения, Firebase переименовывает функцию в следующем формате: ext-extension-instance-id-function-name.

Ниже приведены примеры текста, который можно включить в файл POSTINSTALL расширения. После установки в консоли Firebase отображается содержимое файла POSTINSTALL, а ссылки заменяются фактическими значениями, заданными для установленного экземпляра. Например, если вы определили функцию с названием yourFunction, то можете включить в нее следующие элементы (если применимо):

• Для функций HTTP onRequest

  To trigger this extension, make a request to or visit the following URL:
  **`${function:yourFunction.url}`**.
  

• Для вызываемых функций HTTP (onCall)

  This extension is implemented as an HTTP callable function. To call it from your client app,
  follow the instructions in the
  [callable functions documentation](https://firebase.google.com/docs/functions/callable#call_the_function).
  The name of the function to call is **`${function:yourFunction.name}`**,
  and its region is **`${function:yourFunction.location}`**.
  

Важно! Чтобы пользователи могли использовать расширение, активируемое HTTP-запросом, им нужно сделать функции, развернутые для расширения, общедоступными. Подробные инструкции для пользователей приведены в шаблонах текста выше.

Как написать файл CHANGELOG

Что содержится в этом файле?

У каждого расширения должен быть файл CHANGELOG.md, в котором задокументированы изменения, включенные в каждую новую версию расширения. Каждую версию нужно поместить под заголовком второго уровня (##). В остальном вы можете использовать любое форматирование Markdown.

Ниже приведен пример фрагмента кода из одного из официальных расширений.

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

Где пользователи видят этот контент?

• В консоли Firebase и CLI, когда пользователи обновляют ваше расширение до новой версии. В консоли Firebase и CLI отображаются только изменения, которые вступят в силу, если пользователь завершит обновление.
• Хранилище исходного кода расширения (в каталоге расширения).