Crea la documentación para el usuario de la extensión

Cada extensión debe tener documentación que les enseñe a los usuarios qué hace y cómo usarla.

La documentación mínima y obligatoria es este conjunto de tres archivos de Markdown:

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

Además, te recomendamos proporcionar los siguientes documentos:

• Un archivo README para el repositorio público de la extensión
• Instructivos, guías y referencias de mayor extensión que se publicaron en tu sitio web y tengan vinculación a tu PREINSTALL.md

Para conocer algunas prácticas recomendadas, además de expresiones y estructuras comunes, te recomendamos revisar los archivos disponibles con las Extensiones de Firebase oficiales.

Crea un archivo README

El directorio de la extensión puede contener un archivo README. Ten en cuenta que el comando firebase ext:dev:init no genera uno automáticamente.

Sin embargo, Firebase CLI admite el siguiente comando de conveniencia para generar automáticamente un archivo README con contenido extraído de los archivos extension.yaml y PREINSTALL.md:

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

Todos los archivos README de las Extensiones de Firebase oficiales se generan con este comando.

Agrega información de instalación

Después de escribir o generar un archivo README, agrégale la información de la instalación. Puedes usar el siguiente fragmento como plantilla:

---

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

---

Escribe un archivo PREINSTALL

El archivo PREINSTALL es la descripción general de la extensión, una especie de página de “marketing”.

¿Qué contiene este archivo?

• Descripción completa de la funcionalidad de la extensión
• Lista de requisitos, como la configuración de la base de datos o el acceso a un servicio que no es de Google (ejemplo)
• Descripción breve de las tareas previas a la instalación y sus instrucciones
• Descripción breve de las tareas posteriores a la instalación (ejemplo). Las instrucciones detalladas se encuentran en POSTINSTALL
• Descripción breve de las implicaciones de facturación (comienza con texto estándar)

¿Dónde se muestra este contenido al usuario?

• En la página de la extensión, en extensions.dev
• En el repositorio de código fuente de la extensión (dentro del directorio de la extensión)
• Como parte del archivo README de la extensión (si usas la marca --markdown > README.md de Firebase CLI)

Los archivos PREINSTALL no pueden acceder a los valores de los parámetros de la extensión, por lo que no debes esperar que las referencias de parámetros se procesen con valores reales.

¿Cuáles son algunas de las prácticas recomendadas?

• Si es posible, limita el contenido del archivo PREINSTALL a una página.
• Proporciona el nivel de detalle que el usuario final necesita saber antes de instalar la extensión.
• Incluye instrucciones detalladas en el archivo POSTINSTALL o en otros archivos complementarios.
• Menciona brevemente si proporcionas otras herramientas o secuencias de comandos para admitir la extensión.

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

Escribe un archivo POSTINSTALL

El archivo POSTINSTALL es la página de instrucciones detalladas para después de la instalación de la extensión.

¿Qué contiene este archivo?

• Instrucciones detalladas para cualquier tarea obligatoria posterior a la instalación, como configurar reglas de seguridad de Firebase o agregar código del cliente (ejemplo)
• Instrucciones genéricas para probar la extensión instalada de inmediato (por ejemplo, “Ve a la consola y realiza esta acción”)
• Información básica sobre la activación de la extensión, especialmente para las extensiones activadas por solicitudes HTTP
• Instrucciones breves para supervisar la extensión instalada (comienza con texto estándar)

¿Dónde se muestra este contenido al usuario?

• En Firebase console, después de que un usuario instale tu extensión (en la tarjeta de detalles de la extensión instalada)

  • Asegúrate de revisar cómo se muestra el contenido de POSTINSTALL. Para ello, instala la extensión en un proyecto real.

• En el repositorio de código fuente de la extensión (dentro del directorio de la extensión)

Los archivos POSTINSTALL pueden acceder a los valores de los parámetros y a muchas variables relacionadas con la función para la extensión. Cuando se muestra el contenido de POSTINSTALL en Firebase console, se muestran los valores reales en lugar de las referencias de parámetros o variables. Obtén más información sobre cómo hacer referencia a parámetros y variables en el archivo POSTINSTALL.

¿Cuáles son algunas de las prácticas recomendadas?

• El contenido completo del archivo POSTINSTALL debe ser conciso pero descriptivo.
• Divide el contenido con encabezados para separar las tareas o los conceptos distintos.
• Considera publicar instrucciones detalladas para un flujo de trabajo o una tarea específicos en tu sitio web (ejemplo) o en archivos de Markdown complementarios del repositorio de extensiones (ejemplo).
• Haz referencias a parámetros y variables relacionadas con funciones para que el usuario pueda ver sus valores configurados en el contexto de las instrucciones.

Haz referencia a parámetros y variables

Después de la instalación, Firebase console muestra el contenido del archivo POSTINSTALL de la extensión. Si haces referencia a parámetros y variables relacionadas con funciones (consulta la tabla a continuación) en el archivo POSTINSTALL, la consola propagará estas referencias con los valores reales para la instancia instalada.

Accede a los valores de parámetros configurados en el archivo POSTINSTALL con la siguiente sintaxis: ${param:PARAMETER_NAME}

También puedes hacer referencia a las siguientes variables relacionadas con funciones solo en el archivo POSTINSTALL. Firebase admite estas variables para que puedas brindar orientación a los usuarios con más facilidad después de la instalación. Solo están disponibles para su uso en el archivo POSTINSTALL porque los valores de estas variables no están disponibles hasta después de la instalación.

En esta tabla function-name es el valor del campo name en el objeto del recurso de la función dentro de extension.yaml.

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.

Documenta cómo activar una extensión

En la documentación para el usuario de la extensión, debes indicar a los usuarios cómo activar la extensión. Estas instrucciones pueden ser tan detalladas como sea necesario, pero ten en cuenta las prácticas recomendadas para redactar un archivo POSTINSTALL. Para obtener orientación sobre cómo proporcionar estas instrucciones, expande la siguiente sección que corresponde a tu extensión.

Escribe un archivo CHANGELOG

¿Qué contiene este archivo?

Toda extensión debe tener un archivo CHANGELOG.md que documente los cambios incluidos en cada versión nueva de la extensión que publiques. Coloca cada versión en un encabezado de nivel 2 (##), de lo contrario, puedes usar el formato de Markdown que quieras.

El siguiente ejemplo es un extracto de una de las extensiones oficiales:

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

¿Dónde se muestra este contenido al usuario?

• En Firebase console y la CLI, cuando los usuarios actualicen a la versión nueva de tu extensión (Firebase console y la CLI solo muestran los cambios que se aplicarían si el usuario completara la actualización)
• El repositorio del código fuente de tu extensión (dentro del directorio de la extensión)