16.4. Rilasciare il tuo plugin

Una volta che il tuo plugin è pronto e pensi che possa essere utile a qualcuno, non esitare a caricarlo su Repository ufficiale dei plugin Python. In quella pagina puoi trovare anche le linee guida su come preparare il plugin per farlo funzionare bene con l’installatore di plugin. Oppure, nel caso in cui vuoi creare un tuo repository di plugin, crea un semplice file XML che elenchi i plugin e i relativi metadati.

Presta particolare attenzione ai seguenti suggerimenti:

16.4.1. Metadati e nomi

• evita di utilizzare un nome troppo simile a quello di plugin esistenti

• se il tuo plugin ha una funzionalità simile a quella di un plugin esistente, spiega le differenze nel campo About, in modo che l’utente sappia quale utilizzare senza doverlo installare e testare

• evita di ripetere «plugin» nel nome del plugin stesso

• utilizza il campo Descrizione nei metadati per una descrizione di 1 linea, il campo About per istruzioni più dettagliate

• includi un repository di codice, un bug tracker e una home page; questo aumenterà notevolmente le possibilità di collaborazione e può essere realizzato molto facilmente con una delle infrastrutture web disponibili (GitHub, GitLab, Bitbucket, ecc.).

• scegli con cura i tag: evita quelli poco informativi (ad es. vettoriali) e preferisci quelli già utilizzati da altri (vedi il sito web del plugin)

• aggiungi un’icona appropriata, non lasciare quella predefinita; vedi l’interfaccia di QGIS per un suggerimento sullo stile da usare

16.4.2. Codice e guida

• non includere file generati (ui_*.py, resources_rc.py, file di aiuto generati…) e roba inutile (ad esempio .gitignore) nel repository

• aggiungi il plugin al menu appropriato (Vector, Raster, Web, Database)

• quando è opportuno (plugin che eseguono analisi), valuta la possibilità di aggiungere il plugin come sottoplugin del framework Processing: ciò consentirà agli utenti di eseguirlo in batch, di integrarlo in flussi di lavoro più complessi e vi libererà dall’onere di progettare un’interfaccia

• includi almeno una documentazione minima e, se utile per il test e la comprensione, dei dati di esempio.

16.4.3. Repository ufficiale dei plugin Python

Puoi trovare il repository ufficiale dei plugin Python all’indirizzo https://plugins.qgis.org/.

Per utilizzare il repository ufficiale devi ottenere un OSGEO ID dal portale web OSGEO.

Una volta che hai caricato il tuo plugin, questo verrà approvato da un membro dello staff e ti verrà notificato.

**DA FARE: **

Inserisci un link al documento di governance

16.4.3.1. Permessi

Queste regole sono state implementate nel repository ufficiale dei plugin:

• ogni utente registrato può aggiungere un nuovo plugin

• Gli utenti staff possono approvare o disapprovare tutte le versioni dei plugin.

• Gli utenti che hanno il permesso speciale plugins.can_approve fanno approvare automaticamente le versioni che caricano.

• Gli utenti che hanno il permesso speciale plugins.can_approve possono approvare le versioni caricate da altri, purché siano nell’elenco dei proprietari dei plugin.

• un determinato plugin può essere cancellato e modificato solo dagli utenti staff e dai proprietari di plugin

• se un utente senza il permesso plugins.can_approve carica una nuova versione, la versione del plugin viene automaticamente non approvata.

16.4.3.2. Gestione del Trust

I membri dello staff possono concedere trust ai creatori di plugin selezionati impostando il permesso plugins.can_approve attraverso l’applicazione front-end.

La visualizzazione dei dettagli del plugin offre collegamenti diretti per concedere la fiducia al creatore del plugin o ai proprietari del plugin.

16.4.3.3. Validazione

I metadati del plugin vengono importati e convalidati automaticamente dal pacchetto compresso quando il plugin viene caricato.

Ecco alcune regole di validazione che dovresti conoscere quando vuoi caricare un plugin sul repository ufficiale:

1. il nome della cartella principale contenente il plugin deve contenere solo caratteri ASCII (A-Z e a-z), cifre e i caratteri underscore (_) e meno (-), inoltre non può iniziare con una cifra

2. metadata.txt è richiesto

3. tutti i metadati richiesti elencati in metadata table devono essere presenti

4. il campo di metadati version deve essere univoco

16.4.3.4. Struttura Plugin

In base alle regole di convalida, il pacchetto compresso (.zip) del plugin deve avere una struttura specifica per essere convalidato come plugin funzionale. Poiché il plugin verrà decompresso all’interno della cartella plugins dell’utente, deve avere una propria cartella all’interno del file .zip per non interferire con altri plugin. I file obbligatori sono: metadata.txt e __init__.py. Ma sarebbe bello avere un README e naturalmente un’icona per rappresentare il plugin (resources.qrc). Di seguito è riportato un esempio di come dovrebbe apparire un plugin.zip.

plugin.zip
  pluginfolder/
  |-- i18n
  |   |-- translation_file_de.ts
  |-- img
  |   |-- icon.png
  |   `-- iconsource.svg
  |-- __init__.py
  |-- Makefile
  |-- metadata.txt
  |-- more_code.py
  |-- main_code.py
  |-- README
  |-- resources.qrc
  |-- resources_rc.py
  `-- ui_Qt_user_interface_file.ui