Pubblicare l'estensione

Questa pagina spiega come pubblicare un'estensione nell'hub delle estensioni.

Prima di iniziare

Per pubblicare un'estensione, devi prima registrarti come publisher di estensioni.

Fonti verificabili

Tutte le estensioni pubblicate nell'hub delle estensioni devono avere un'origine verificabile pubblicamente. Anziché caricare il codice sorgente dell'estensione direttamente nell'hub delle estensioni, devi specificare la posizione dell'origine e l'hub delle estensioni lo scaricherà e lo creerà da lì.

Al momento, ciò significa rendere disponibile il codice sorgente dell'estensione in un repository GitHub pubblico.

Il caricamento da un'origine verificabile offre diversi vantaggi:

  • Gli utenti possono ispezionare il codice sorgente della revisione specifica dell'estensione che verrà installata.
  • Puoi assicurarti di caricare solo ciò che intendi caricare e non, ad esempio, il lavoro in corso o i file non necessari rimasti dallo sviluppo.

Ciclo di sviluppo consigliato

Gli strumenti di sviluppo di Firebase Extensions supportano il caricamento delle versioni pre-release delle estensioni, il che ti consente di testare facilmente le estensioni e la procedura di installazione delle estensioni nello stesso ambiente in cui verranno rilasciate.

Questa funzionalità consente un ciclo di sviluppo come il seguente:

  1. Sviluppa e itera rapidamente l'estensione utilizzando la Firebase Emulator Suite.

  2. Testa l'estensione in un progetto reale installandola da un'origine locale:

    firebase ext:install /path/to/extension
firebase deploy --only extensions

  3. Carica una versione pre-release nell'hub delle estensioni (vedi di seguito). Distribuisci il link di installazione per test più ampi e itera caricando altre versioni pre-release, se necessario.

  4. Carica la versione finale e stabile nell'hub delle estensioni (vedi di seguito) e inviala per la revisione. Se l'estensione supera la revisione, verrà pubblicata nell'hub delle estensioni.

  5. Incrementa il numero di versione in extension.yaml e ripeti questo ciclo per la versione successiva dell'estensione.

Caricare una nuova estensione

Per caricare un'estensione per la prima volta:

  1. Facoltativo: esegui il commit del codice in un repository GitHub pubblico.

  2. Esegui il comando ext:dev:upload dell'interfaccia a riga di comando di Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Codice sorgente locale

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

    Nell'invocazione del comando, specifica quanto segue:

    • L'ID publisher che hai registrato.

    • Una stringa ID che identificherà l'estensione. Assegna alle estensioni il seguente formato: firebase-product-description-of-tasks-performed. Ad esempio: firestore-bigquery-export

    Il comando ti chiederà ulteriori informazioni:

    • Se esegui il caricamento da GitHub:

      • L'URL del repository dell'estensione in GitHub. Tieni presente che un repository può contenere più estensioni, purché ogni estensione abbia una root univoca.

        Quando carichi una nuova estensione per la prima volta, il repository viene registrato come origine canonica per l'estensione.

      • La directory nel repository che contiene l'estensione.

      • Il riferimento Git del commit da cui vuoi creare l'origine della versione dell'estensione. Può essere un hash di commit, un tag o un nome di ramo.

    • La fase di release della versione che stai caricando.

      Le fasi alpha, beta e rc (candidato per la release) vengono utilizzate per caricare le versioni pre-release da installare per i tester. Utilizza una di queste fasi per il caricamento iniziale di una nuova estensione.

      La fase stable viene utilizzata per le release pubbliche da pubblicare nell'hub delle estensioni. Il caricamento di una release stable avvierà automaticamente una revisione e, se la supera, pubblicherà l'estensione.

    Tieni presente che non devi specificare un numero di versione: questo valore proviene dal file extension.yaml. Quando carichi una versione pre-release dell'estensione, la fase e il numero di caricamento vengono aggiunti alla versione. Ad esempio, se extension.yaml specifica la versione 1.0.1 e carichi un candidato per la release, il risultato sarà la versione 1.0.1-rc.0; se carichi un altro candidato per la release della stessa versione, il conteggio verrà incrementato automaticamente, con il risultato 1.0.1-rc.1 e così via.

Ora che hai caricato una versione pre-release dell'estensione, puoi condividerla con altri utenti per i test. Gli utenti possono installare l'estensione in due modi:

  • Con la console: gli utenti possono installare l'estensione facendo clic su un link con il seguente formato:

    https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

    Puoi condividere il link diretto con i tuoi tester.

  • Con l'interfaccia a riga di comando: gli utenti possono installare l'estensione passando la stringa ID dell'estensione al comando ext:install:

    firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id

Caricare una versione aggiornata

Dopo aver caricato la prima versione di un'estensione, puoi caricare gli aggiornamenti per correggere i problemi, aggiungere funzionalità o avanzare la fase di release. Quando carichi una nuova versione, agli utenti che hanno installato una versione precedente della tua estensione verrà chiesto di eseguire l'upgrade nella Firebase console.

Per caricare un aggiornamento:

  1. Facoltativo: esegui il commit del codice in un repository Git pubblico.

  2. Esegui il comando ext:dev:upload dell'interfaccia a riga di comando di Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Questa volta non ti verrà chiesto di specificare il repository GitHub o la directory root dell'estensione, perché sono già stati configurati per l'estensione. Se nel frattempo hai eseguito il refactoring della struttura del repository o hai eseguito la migrazione a un nuovo repository, puoi modificarli con gli argomenti del comando --root e --repo.

    Codice sorgente locale

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

Inviare un'estensione per la pubblicazione

Quando tutto è pronto per rilasciare pubblicamente l'estensione:

  1. Esegui il commit del codice in un repository Git pubblico. (Obbligatorio per le release pubbliche.)

  2. Esegui il comando ext:dev:upload dell'interfaccia a riga di comando di Firebase, specificando stable come fase di release:

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. Se hai già pubblicato una versione dell'estensione, il caricamento di una nuova release stabile invierà automaticamente l'estensione per la revisione.

    Se hai caricato la prima release stabile dell'estensione, trova l'estensione su la tua dashboard del publisher, e fai clic su Pubblica nell'hub delle estensioni.

Una volta inviata, la revisione può richiedere alcuni giorni. Se accettata, l'estensione verrà pubblicata nell'hub delle estensioni. Se viene rifiutata, riceverai un messaggio che spiega il motivo; potrai quindi risolvere i problemi segnalati e inviare nuovamente la richiesta di revisione.

Per velocizzare la revisione e aumentare le probabilità di superarla al primo tentativo, prima di inviare la richiesta, controlla quanto segue:

  • Hai testato a fondo l'estensione e la procedura di installazione.
  • La documentazione è completa e corretta e viene visualizzata correttamente nella console Firebase.
  • Il nome e il branding del publisher ti identificano in modo chiaro e preciso come publisher.
  • Il nome, la descrizione e l'icona dell'estensione rappresentano in modo chiaro e preciso lo scopo dell'estensione.
  • Hai applicato tag utili e precisi.
  • Hai dichiarato in extension.yaml tutte le API Google e non Google che utilizzi e tutti i tipi di eventi emessi dall'estensione.
  • Richiedi l'accesso solo ai ruoli necessari per il funzionamento dell'estensione e hai spiegato chiaramente agli utenti perché hai bisogno di questo accesso.
  • I file sorgente sono chiaramente concessi in licenza ai sensi di Apache-2.0.

Gestire le estensioni caricate e pubblicate

Elencare le estensioni caricate

Per elencare le estensioni che hai caricato con il tuo ID publisher, procedi in uno dei seguenti modi:

Dashboard del publisher

Visualizzale nella dashboard del publisher.

Interfaccia a riga di comando di Firebase

Esegui il comando ext:dev:list:

firebase ext:dev:list your_publisher_id

Visualizzare l'utilizzo delle estensioni caricate

Per visualizzare l'utilizzo delle estensioni che hai caricato con il tuo ID publisher, procedi in uno dei seguenti modi:

Dashboard del publisher

La dashboard del publisher contiene metriche di utilizzo cumulative per tutte le estensioni e metriche individuali per ogni estensione.

Interfaccia a riga di comando di Firebase

Esegui il comando ext:dev:usage:

firebase ext:dev:usage your_publisher_id

Deprecare una versione di un'estensione

A un certo punto, potresti voler deprecare una versione precedente dell'estensione. Ad esempio, se rilasci una nuova versione che corregge un bug critico o aggiorna una dipendenza con un importante aggiornamento della sicurezza, è importante impedire ai nuovi utenti di installare una versione precedente e incoraggiare gli utenti esistenti a eseguire l'upgrade.

Per deprecare una versione di un'estensione, procedi in uno dei seguenti modi:

Dashboard del publisher

  1. Nella dashboard del publisher, fai clic sull'estensione per aprire la visualizzazione dei dettagli.
  2. Seleziona la versione che vuoi deprecare.
  3. Fai clic su Depreca versione.

Interfaccia a riga di comando di Firebase

Esegui il comando ext:dev:deprecate:

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

Puoi specificare una singola versione o un intervallo di versioni. Esempi:

  • 1.0.2
  • 1.1.0-1.1.7
  • <1.2.0
  • 1.1.*

Le versioni deprecate di un'estensione non sono elencate nell'hub delle estensioni e non possono essere installate. Gli utenti i cui progetti hanno installato una versione deprecata vedranno un messaggio che li incoraggia a eseguire l'upgrade; nel frattempo, possono comunque utilizzare e riconfigurare l'estensione.

Se tutte le versioni di un'estensione sono deprecate, l'estensione viene considerata deprecata e verrà rimossa dall'elenco dell'hub delle estensioni. Il caricamento di una nuova versione di un'estensione deprecata avvierà automaticamente una revisione e, se accettata, la pubblicherà di nuovo nell'hub delle estensioni.

Per annullare la deprecazione, utilizza la dashboard del publisher o esegui il comando ext:dev:undeprecate dell'interfaccia a riga di comando di Firebase:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Appendice: risoluzione degli errori di build

Quando carichi l'estensione, il backend crea prima il codice sorgente utilizzando la seguente procedura:

  1. Clona il repository GitHub ed estrae il riferimento di origine specificato.

  2. Installa le dipendenze NPM eseguendo npm clean-install in ogni directory di origine della funzione specificata in extension.yaml (vedi sourceDirectory nelle risorse di Cloud Functions).

    Tieni presente quanto segue:

    • Ogni file package.json deve avere un file package-lock.json corrispondente. Per ulteriori informazioni, consulta npm-ci.

    • Gli script post-installazione non verranno eseguiti durante l'installazione delle dipendenze. Se la build del codice sorgente si basa su script post-installazione, esegui il refactoring prima del caricamento.

  3. Crea il codice eseguendo npm run build in ogni directory di origine della funzione specificata in extension.yaml.

Nel pacchetto di estensione finale che verrà condiviso verrà salvata solo la directory root dell'estensione.

Se ricevi errori di build durante il caricamento dell'estensione, replica i passaggi di build sopra descritti localmente in una nuova directory finché non vengono visualizzati errori, quindi riprova a caricare.