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 editore 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 località di origine e l'hub di estensione 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 una fonte verificabile presenta diversi vantaggi:

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

Ciclo di sviluppo consigliato

Gli strumenti di sviluppo di Firebase Extensions supportano il caricamento di versioni pre-release delle tue estensioni, il che semplifica il test delle tue estensioni e del processo di installazione delle estensioni nello stesso ambiente in cui verranno rilasciate alla fine.

Questa funzionalità rende possibile un ciclo di sviluppo come il seguente:

  1. Sviluppare ed eseguire rapidamente l'iterazione dell'estensione utilizzando la suite di emulatori Firebase.

  2. Testa l'estensione in un progetto reale installandola dal codice sorgente locale:

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

  3. Carica una versione pre-release in Extensions Hub (vedi di seguito). Distribuisci il link di installazione per test più ampi e esegui l'iterazione caricando altre versioni pre-release, se necessario.

  4. Carica la versione finale 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. Aumenta 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

    Origine 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 identifica l'estensione. Assegna alle estensioni un nome con 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 su GitHub. Tieni presente che un repository può contenere più estensioni, a condizione che ciascuna abbia una radice univoca.

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

      • La directory nel repository che contiene l'estensione.

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

    • La fase di rilascio della versione che stai caricando.

      Le fasi alpha, beta e rc (release candidate) sono destinate al caricamento delle versioni pre-release da installare da parte dei 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 attiverà automaticamente una revisione e, se supera la verifica, l'estensione verrà pubblicata.

    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, seextension.yaml specifica la versione 1.0.1 e carichi una release candidate,1.0.1-rc.0 sarà la versione risultante; il caricamento di un'altra release candidate della stessa versione incrementerà automaticamente il conteggio,1.0.1-rc.1 e così via.

Ora che hai caricato una versione pre-release dell'estensione, puoi condividerla con altri utenti per il test. Gli utenti possono installare la tua 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 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

Carica una versione aggiornata

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

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 radice dell'estensione poiché sono già stati configurati per l'estensione. Se nel frattempo hai ristrutturato la struttura del repository o hai eseguito la migrazione a un nuovo repository, puoi modificarli con gli argomenti di comando --root e --repo.

    Origine 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 rilascio:

    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, individuala nella 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 la richiesta viene rifiutata, riceverai un messaggio che ne spiega il motivo. Potrai quindi risolvere i problemi segnalati e inviare nuovamente la richiesta per la revisione.

Per velocizzare la revisione e aumentare le probabilità di superare il primo tentativo, prima di inviarlo, verifica 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 editore.
  • 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.
  • In extension.yaml hai dichiarato 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 tuoi file di origine sono concessi in licenza ai sensi dei termini 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 nel seguente modo:

Dashboard del publisher

Visualizzarli 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, svolgi una delle seguenti operazioni:

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

Rifiutare una versione di un'estensione

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

Per ritirare 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 relativa visualizzazione dei dettagli.
  2. Seleziona la versione che vuoi ritirare.
  3. Fai clic su Ritira 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 nei cui progetti è installata una versione ritirata visualizzeranno un messaggio che li invita a eseguire l'upgrade. Nel frattempo, potranno comunque utilizzare e riconfigurare l'estensione.

Se tutte le versioni di un'estensione sono ritirate, l'estensione stessa viene considerata ritirata e verrà rimossa dall'hub delle estensioni. Il caricamento di una nuova versione di un'estensione deprecata avvierà automaticamente una revisione e, al momento dell'accettazione, pubblicherà nuovamente l'estensione nell'hub delle estensioni.

Per annullare un ritiro, 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 compilazione

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

  1. Clona il repository GitHub e esegue il check out del 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 in Risorse di Cloud Functions).

    Tieni presente quanto segue:

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

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

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

Solo la directory root dell'estensione verrà salvata nel pacchetto di estensioni finale che verrà condiviso.

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