Каждое расширение должно иметь документацию, которая учит пользователей тому, что делает расширение и как его использовать.
Минимальная необходимая документация ��� это набор из трех файлов уценки:
-
PREINSTALL.md
-
POSTINSTALL.md
-
CHANGELOG.md
Кроме того, вам следует также рассмотреть возможность производства:
- Файл
README
для общедоступного репозитория расширения. - Подробные учебные пособия, руководства и ссылки опубликованы на вашем веб-сайте и связаны с вашим
PREINSTALL.md
.
Чтобы изучить некоторые рекомендации, а также общие формулировки и структуру, мы рекомендуем просмотреть файлы, доступные с официальными расширениями Firebase .
Создание README
Каталог расширений может дополнительно содержать README. Обратите внимание, что команда firebase ext:dev:init
не создает ее автоматически.
Однако интерфейс командной строки 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
представляет собой обзор вашего расширения, своего рода «маркетинговую» страницу.
Какой контент в этом файле?
- Подробное описание функциональности вашего расширения.
- Список предварительных требований, таких как настройка базы данных или доступ к службе, не принадлежащей Google ( пример ).
- Краткое описание любых предустановочных задач и их инструкций.
- Краткое описание любых задач после установки ( пример ) (подробные инструкции находятся в
POSTINSTALL
) - Краткое описание последствий для выставления счетов (начните с шаблонного текста ).
Где этот контент отображается пользователю?
![Изображение предустановленного контента в консоли Firebase](https://cdn.statically.io/img/firebase.google.com/static/docs/extensions/publishers/images/preinstall_thumb.png?hl=ru)
- На странице расширения на Extensions.dev .
- Репозиторий исходного кода вашего расширения (внутри каталога расширений).
- Как часть README расширения (если вы используете интерфейс командной строки Firebase
--markdown > README.md
)
PREINSTALL
не могут получить доступ к значениям параметров расширения, поэтому не следует ожидать, что ссылки на параметры будут отображаться с фактическими значениями.
Каковы некоторые лучшие практики?
По возможности сохраняйте полное содержимое файла PREINSTALL
на одной странице .Обеспечьте уровень детализации, который абсолютно необходимо знать конечному пользователю перед установкой расширения. Поместите подробные инструкции в файл POSTINSTALL
или другие дополнительные файлы.Кратко укажите, предоставляете ли вы другие инструменты или сценарии для поддержки расширения.
Написание файла POSTINSTALL
POSTINSTALL
POSTINSTALL
— это страница с подробными инструкциями по установке вашего расширения.
Какой контент в этом файле?
Подробные инструкции для любых необходимых задач после установки, таких как настройка правил безопасности Firebase или добавление клиентского кода ( пример ). Общие инструкции, как сразу опробовать установленное расширение (например, «зайдите в консоль, затем сделайте это») Основная информация о том, как активировать расширение, особенно для расширений, активируемых HTTP-запросом. Краткие инструкции по мониторингу установленного расширения (начните с шаблонного текста )
Где этот контент отображается пользователю?
![Изображение контента после установки в консоли Firebase](https://cdn.statically.io/img/firebase.google.com/static/docs/extensions/publishers/images/postinstall_thumb.png?hl=ru)
В консоли Firebase после того, как пользователь установит ваше расширение (в подробной карточке установленного расширения). Обязательно проверьте отображение содержимого POSTINSTALL
, установив расширение в реальный проект .
Репозиторий исходного кода вашего расширения (внутри каталога расширений).
POSTINSTALL
могут получить доступ к значениям параметров и нескольким переменным, связанным с функциями, для расширения. Когда содержимое POSTINSTALL
отображается в консоли Firebase, отображаются фактические значения , а не ссылки на параметры или переменные. Ниже вы узнаете, как ссылаться на параметры и переменные в файле POSTINSTALL
.
Каковы некоторые лучшие практики?
Полное содержимое файла POSTINSTALL
должно быть кратким, но информативным.Разделите контент, используя заголовки, чтобы разделить отдельные задачи или концепции. Рассмотрите возможность публикации подробных инструкций для конкретного рабочего процесса или задачи на своем веб-сайте ( пример ) или в дополнительных файлах уценки в репозитории расширений ( пример ). Ссылайтесь на параметры и переменные, связанные с функциями , чтобы пользователь видел их настроенные значения в контексте инструкций.
Ссылки на параметры и переменные
POSTINSTALL
расширения. Если вы ссылаетесь на параметры и переменные, связанные с функциями (см. таблицу ниже) в файле POSTINSTALL
, консоль заполняет эти ссылки фактическими значениями для установленного экземпляра.
POSTINSTALL
используя следующий синтаксис:${param: PARAMETER_NAME }
POSTINSTALL
. Firebase поддерживает эти переменные, чтобы вам было легче предоставлять рекомендации своим пользователям после установки. Их можно использовать только в файле POSTINSTALL
, поскольку значения этих переменных доступны только после установки.
name
в объекте ресурса функции в extension.yaml
.
Ссылка на переменную, связанную с функцией | Описание | Значение переменной (автоматически заполняется Firebase после установки расширения) |
---|---|---|
${function: function-name .location} | ||
Место , где раз��ерн��та функци�� | Пр��мер значения:us-central1 | |
${function: function-name .name} | ||
Имя окончательно развернутой функции, включающее идентификатор экземпляра расширения. | Общий формат: Пример значения: | |
${function: function-name .url} (применимо только для функций HTTP) | ||
URL-адрес окончательной развернутой функции, к которой клиентский код может отправлять HTTP-запросы. | Общий формат: Пример значения: |
Документирование того, как активировать расширение
POSTINSTALL
. Чтобы получить инструкции по предоставлению этих инструкций, разверните раздел ниже, который относится к вашему расширению.
Запись файла 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 и интерфейс командной строки отображают только те изменения, которые вступят в силу, если пользователь завершит обновление. Репозиторий исходного кода вашего расширения (внутри каталога расширения).