Каждое расширение должно сопровождаться документацией, которая объясняет пользователям, что оно делает и как им пользоваться.
Минимально необходимая документация состоит из трех файлов Markdown:
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
Кроме того, вам также следует рассмотреть возможность производства:
- Файл
READMEдля общедоступного репозитория расширения. - Более подробные руководства, инструкции и справочные материалы публикуются на вашем собственном веб-сайте и содержат ссылки на них в файле
PREINSTALL.md.
Чтобы ознакомиться с передовыми методами, распространенными формулировками и структурой, мы рекомендуем изучить файлы, доступные в официальных расширениях Firebase .
Создание файла README
В каталоге расширений может содержаться файл README (при желании). Обратите внимание, что команда firebase ext:dev:init не генерирует его автоматически.
Однако Firebase CLI поддерживает следующую удобную команду для автоматической генерации файла README , содержащего содержимое, взятое из файла extension.yaml и файла PREINSTALL.md :
firebase ext:info ./path/to/extension --markdown > README.md
Все файлы README для официальных расширений Firebase генерируются с помощью этой команды.
Добавить информацию об установке
После написания или создания файла README добавьте в него информацию об установке. В качестве шаблона можно использовать следующий фрагмент кода:
--- ## 🧩 Install this extension ### Console [][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 — это обзор вашего расширения, своего рода «маркетинговая» страница.
Что содержится в этом файле?
- Подробное описание функциональности вашего расширения.
- Список необходимых условий, таких как настройка базы данных или доступ к сервису, не принадлежащему Google ( пример ).
- Краткое описание любых подготовительных работ и инструкции по их выполнению.
- Краткое описание любых задач, выполняемых после установки ( пример ) (подробные инструкции находятся в
POSTINSTALL) - Краткое описание любых вопросов, связанных с выставлением счетов (начните со стандартного текста ).
Где этот контент отображается пользователю?
Консоль Firebase">
Консоль Firebase">
- На странице расширения на сайте extensions.dev .
- Ваш репозиторий исходного кода для вашего расширения (внутри каталога расширений)
- В файле README расширения (если вы используете Firebase CLI)
--markdown > README.md
Файлы PREINSTALL не имеют доступа к значениям параметров расширения, поэтому не следует ожидать, что ссылки на параметры будут отображаться с фактическими значениями.
Какие существуют лучшие практики?
- По возможности, уместите всё содержимое файла
PREINSTALLна одной странице . - Предоставьте пользователю только ту информацию, которая абсолютно необходима перед установкой расширения.
- Подробные инструкции следует разместить в файле
POSTINSTALLили в других дополнительных файлах. - Кратко укажите, если вы предоставляете другие инструменты или скрипты для поддержки расширения.
Мы рекомендуем использовать как можно больше следующего стандартного текста, подходящего для вашего расширения. Мы привели несколько примеров, но самое важное — убедиться, что указаны все платные сервисы Google и другие.
Для получения точной информации о ценах на продукцию вы можете использовать следующие ресурсы:
Для всех расширений включите этот раздел, чтобы помочь пользователям понять особенности выставления счетов:
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 после установки пользователем вашего расширения (в подробной карточке установленного расширения)
- Обязательно проверьте отображение содержимого
POSTINSTALL, установив расширение в реальном проекте .
- Обязательно проверьте отображение содержимого
Ваш репозиторий исходного кода для вашего расширения (внутри каталога расширений)
Файлы POSTINSTALL позволяют получить доступ к значениям параметров и нескольким переменным, связанным с функциями расширения. При отображении содержимого файла POSTINSTALL в консоли Firebase отображаются фактические значения , а не ссылки на параметры или переменные. Подробнее о том, как ссылаться на параметры и переменные в файле POSTINSTALL , см. ниже.
Какие существуют лучшие практики?
- Содержимое файла
POSTINSTALLдолжно быть кратким, но содержательным. - Разделите контент на разделы, используя заголовки, чтобы разбить его на отдельные задачи или концепции.
- Рекомендуется опубликовать подробные инструкции для конкретного рабочего процесса или задачи на вашем веб-сайте ( пример ) или в дополнительных файлах Markdown в репозитории расширений ( пример ).
- Справочные параметры и переменные, связанные с функциями , чтобы пользователь видел их настроенные значения в контексте инструкций.
Ссылочные параметры и переменные
После установки консоль Firebase отображает содержимое файла POSTINSTALL расширения. Если в файле POSTINSTALL указаны параметры и переменные, связанные с функциями (см. таблицу ниже), то консоль заполнит эти ссылки фактическими значениями для установленного экземпляра.
Для доступа к заданным значениям параметров в файле POSTINSTALL используйте следующий синтаксис:${param: PARAMETER_NAME }
Вы также можете ссылаться на следующие переменные, связанные с функциями, только в файле POSTINSTALL . Firebase поддерживает эти переменные, чтобы вы могли проще предоставлять инструкции пользователям после установки. Они доступны для использования только в файле POSTINSTALL , поскольку значения для этих переменных становятся доступны только после установки.
В этой таблице function-name — это значение поля name в объекте ресурсов функции в extension.yaml .
| Ссылка на переменную, связанную с функцией | Описание | Значение переменной (автоматически заполняется Firebase после установки расширения) |
|---|---|---|
${function: function-name .location} | ||
| Место развертывания функции | Пример значения:us-central1 | |
${function: function-name .name} | ||
| Название окончательно развернутой функции, включающее идентификатор экземпляра расширения. | Обобщенный формат: Пример значения: | |
${function: function-name .url} (применимо только для HTTP-функций) | ||
| URL-адрес окончательно развернутой функции, к которому клиентский код может отправлять HTTP-запросы. | Обобщенный формат: Пример значения: | |
Мы рекомендуем использовать как можно больше следующего стандартного текста, в зависимости от особенностей вашего расширения.
Для всех расширений добавьте следующий раздел, чтобы помочь пользователям отслеживать установленные расширения:
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-запросом (и, следовательно, расширение), вам необходимо предоставить им имя развернутой функции или ее URL-адрес .
Имя окончательно развернутой функции не совпадает с name , указанным в объекте ресурса функции в extension.yaml . Чтобы обеспечить возможность установки одного и того же расширения в нескольких проектах, Firebase переименовывает функцию в следующем формате:ext- extension-instance-id - function-name .
Ниже приведён предлагаемый шаблонный текст для включения в файл POSTINSTALL вашего расширения. После установки консоль Firebase отобразит содержимое файла POSTINSTALL и заполнит эти ссылки фактическими значениями, настроенными для установленного экземпляра. Например, если вы определили функцию с именем yourFunction , вы можете включить следующее (в зависимости от ситуации):
Для функций HTTP
onRequestTo 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}`**.
Создание файла 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 которые вступят в силу после завершения обновления.
- Репозиторий исходного кода вашего расширения (внутри каталога расширения).