16.5. Uw plug-in uitgeven

Als uw plug-in eenmaal klaar is en u denkt dat de plug-in van nut zou kunnen zijn voor anderen, aarzel dan niet om het te uploaden naar Officiële Python plug-in opslagplaats. Op die pagina kunt u ook richtlijnen vinden voor het verpakken om de plug-in voor te bereiden om goed te werken met het installatieprogramma van plug-ins. Of, in het geval u uw eigen opslagplaats voor plug-ins zou willen inrichten, maak een eenvoudig XML-bestand dat de plug-ins en hun metadata vermeld.

Neem goede notie van de volgende suggesties:

16.5.1. Metadata en namen

• vermijd het gebruiken van een naam die teveel lijkt op die van bestaande plug-ins

• als uw plug-in een soortgelijke functionaliteit heeft als een bestaande plug-in, leg dan de verschillen uit in het vak About, zodat de gebruiker weet welke te gebruiken zonder dat hij hem eerst moet installeren en testen

• vermijd het herhalen van “plug-in” in de naam van de plug-in zelf

• gebruik het veld Description in de metadata voor een omschrijving van één regel, het veld About voor meer gedetailleerde instructies

• neem een code repository, een bug tracker, en een homepage op; dat zal de mogelijkheid tot samenwerken enorm vergroten, en kan zeer eenvoudig worden gedaan met behulp van één van de beschikbare infrastructuren voor het web (GitHub, GitLab, Bitbucket, etc.)

• kies tags met zorg: vermijd de niet-informatieve (bijv. vector) en gebruik bij voorkeur die welke al zijn gebruikt door anderen (bekijk de website van de plug-in)

• voeg een juist pictogram toe, volsta niet met het standaard pictogram; bekijk de interface van QGIS voor een suggestie van de te gebruiken stijl

16.5.2. Code en hulp

• neem geen gegenereerd bestand (ui_*.py, resources_rc.py, gegenereerde Helpbestanden…) op en waardeloos spul (bijv. .gitignore) in de repository

• voeg de plug-in toe aan het toepasselijke menu (Vector, Raster, Web, Database)

• indien van toepassing (plug-ins die analyses uitvoeren), overweeg dan om de plug-in toe te voegen als een subplug-in voor het framework Processing: dat zal het voor gebruikers mogelijk maken het in batch uit te voeren, het te integreren in meer complexe werkstromen, en zal u bevrijden van het ontwerpen van een interface

• neem tenminste minimale documentatie op en, indien nuttig voor testen en begrijpen, voorbeeldgegevens.

16.5.3. Officiële Python plug-in opslagplaats

U vindt de officiële Python plug-in opslagplaats op https://plugins.qgis.org/.

Voor het gebruiken van de officiële opslagplaats moet u een OSGEO ID verkrijgen van het OSGEO webportaal.

Als u uw plug-in eenmaal heeft geüpload, zal die worden gekeurd door een lid van de staf en zult u bericht ontvangen.

TODO:

Een koppeling naar het document voor governance invoegen

16.5.3.1. Rechten

Deze regels zijn geïmplementeerd in de officiële plug-in opslagplaats:

• elke geregistreerde gebruiken mag een nieuwe plug-in toevoegen

• staf-gebruikers mogen alle versies van plug-ins goed- of afkeuren

• gebruikers die het speciale recht plugins.can_approve hebben krijgen de versies die zij uploaden automatisch goedgekeurd

• gebruikers die het speciale recht plugins.can_approve hebben kunnen door anderen geüploade versies goedkeuren zo lang als zij in de lijst plug-in owners staan

• een bepaalde plug-in kan worden verwijderd en bewerkt, alleen door staf-gebruikers en plug-in owners

• als een gebruiker zonder het recht plugins.can_approve een nieuwe versie uploadt, wordt de versie van de plug-in automatisch niet goedgekeurd.

16.5.3.2. Beheer van ‘trust’

Stafleden kunnen het recht trust toekennen aan geselecteerde makers van plug-ins door het instellen van het recht plugins.can_approve door middel van de front-end toepassing.

De gedetailleerde weergave van plug-ins biedt directe koppelingen om trust toe te kennen aan de maker van de plug-in of de plug-in owners.

16.5.3.3. Validatie

Metadata van plug-ins worden automatisch geïmporteerd en gevalideerd vanuit het gecomprimeerde pakket als de plug-in wordt geüpload.

Hier zijn enkele regels voor validatie waarvan u op de hoogte zou moeten zijn wanneer u een plug-in zou willen uploaden naar de officiële opslagplaats:

1. de naam van de hoofdmap die uw plug-in bevat mag alleen ASCII-tekens bevatten (A-Z en a-z), cijfers en het teken underscore (_) en minus (-), ook mag het niet beginnen met een cijfer

2. metadata.txt is vereist

3. alle vereiste metadata vermeld in metadata table moeten aanwezig zijn

4. het veld version voor metadata moet uniek zijn

16.5.3.4. Plug-in structuur

Op grond van de regels voor validatie moet het gecomprimeerde (.zip) pakket van uw plug-in een specifieke structuur hebben om als een functionele plug-in te worden gevalideerd. Omdat de plug-in zal worden uitgepakt binnen de map plug-ins van de gebruiker moet het zijn eigen map binnen het .zip-bestand hebben om niet te interfereren met andere plug-ins. Verplichte bestanden zijn: metadata.txt en __init__.py. Maar het zou leuk zijn om een README te hebben en natuurlijk een pictogram om de plug-in weer te geven (resources.qrc). Hieronder volgt een voorbeeld van hoe een plug-in.zip er uit zou moeten zien.

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