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

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

Минимальная необходимая документация — это набор из трех файлов уценки:

  • 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 )
  • Краткое описание последствий для выставления счетов (начните с шаблонного текста ).

Где этот контент отображается пользователю?

Изображение предустановленного содержимого в <span class= Консоль Firebase">
Предварительная установка контента в консоли Firebase

Большое изображение предустановленного содержимого в <span class= Консоль Firebase">

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

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

Каковы некоторые лучшие практики?

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

Написание файла POSTINSTALL

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

Какое содержимое находится в этом файле?

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

Где этот контент отображается пользователю?

Изображение содержимого после установки в <span class= Консоль Firebase">
Содержимое после установки в консоли Firebase

Большое изображение содержимого после установки в <span class= Консоль Firebase">

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

  • Репозиторий исходного кода вашего расширения (внутри каталога расширений).

Файлы 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}
Имя окончательно развернутой функции, включающее идентификатор экземпляра расширения.

Общий формат:
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 . Чтобы получить инструкции по предоставлению этих инструкций, разверните раздел ниже, который относится к вашему расширению.

Запись файла 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 и интерфейс командной строки отображают только те изменения, которые вступят в силу, если пользователь завершит обновление.
  • Репозиторий исходного кода вашего расширения (внутри каталога расширения).
,

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

Минимальная необходимая документация — это набор из трех файлов уценки:

  • 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 )
  • Краткое описание последствий для выставления счетов (начните с шаблонного текста ).

Где этот контент отображается пользователю?

Изображение предустановленного содержимого в <span class= Консоль Firebase">
Предварительная установка контента в консоли Firebase

Большое изображение предустановленного содержимого в <span class= Консоль Firebase">

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

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

Каковы некоторые лучшие практики?

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

Написание файла POSTINSTALL

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

Какое содержимое находится в этом файле?

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

Где этот контент отображается пользователю?

Изображение содержимого после установки в <span class= Консоль Firebase">
Содержимое после установки в консоли Firebase

Большое изображение содержимого после установки в <span class= Консоль Firebase">

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

  • Репозиторий исходного кода вашего расширения (внутри каталога расширений).

Файлы 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}
Имя окончательно развернутой функции, включающее идентификатор экземпляра расширения.

Общий формат:
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 . Чтобы получить инструкции по предоставлению этих инструкций, разверните раздел ниже, который относится к вашему расширению.

Запись файла 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 и интерфейс командной строки отображают только те изменения, которые вступят в силу, если пользователь завершит обновление.
  • Репозиторий исходного кода вашего расширения (внутри каталога расширения).