Каждое расширение должно иметь документацию, объясняющую пользователям, что делает расширение и как его использовать.
Минимальная необходимая документация — это набор из трех файлов разметки:
-
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 — это обзор вашего расширения, своего рода «маркетинговая» страница.
Какое содержимое находится в этом файле?
- Подробное описание функциональности вашего расширения
- Список предварительных условий, таких как настройка базы данных или доступ к сторонней службе ( пример )
- Краткое описание всех предустановочных задач и их инструкции
- Краткое описание любых задач после установки ( пример ) (подробные инструкции см. в
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должно быть кратким, но описательным. - Разделите контент, используя заголовки, чтобы разбить отдельные задачи или концепции.
- Рассмотрите возможность публикации подробных инструкций для конкретного рабочего процесса или задачи на своем веб-сайте ( пример ) или в дополнительных файлах разметки в репозитории расширений ( пример ).
- Справочные параметры и переменные, связанные с функциями, чтобы пользователь мог видеть их настроенные значения в контексте инструкций.
Ссылочные параметры и переменные
После установки консоль 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 , в котором задокументированы изменения, внесённые в каждую новую версию вашего расширения, которую вы публикуете. Каждую версию следует поместить под заголовком 2-го уровня ( ## ); в противном случае вы можете использовать любое удобное вам форматирование 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 отображаются только те изменения, которые вступят в силу, если пользователь завершит обновление.
- Репозиторий исходного кода вашего расширения (внутри каталога расширения).