16.5. Lançando seu complemento

Quando o seu complemento estiver pronto e você achar que ele pode ser útil para algumas pessoas, não hesite em enviá-lo para Repositório Oficial de complementos Python. Nessa página, você também pode encontrar diretrizes de empacotamento sobre como preparar o complemento para funcionar bem com o instalador do complemento. Ou, caso você queira configurar seu próprio repositório de complementos, crie um arquivo XML simples que listará os complementos e seus metadados.

Por favor, atente especialmente para as seguintes sugestões:

16.5.1. Metadados e nomes

• evite usar um nome muito semelhante aos dos complementos existentes

• se o seu complemento uma funcionalidade semelhante a um complemento existente, explique as diferenças no campo Sobre, para que o usuário saiba qual usar, sem a necessidade de instalá-lo e testá-lo.

• evite repetir “plugin” no nome do próprio complemento

• use o campo de descrição nos metadados para uma descrição de 1 linha, o campo Sobre para obter instruções mais detalhadas

• inclua um repositório de códigos, um rastreador de bug e uma página inicial; isso aumentará muito a possibilidade de colaboração e pode ser feito com muita facilidade com uma das infraestruturas da web disponíveis (GitHub, GitLab, Bitbucket, etc.)

• escolha as tags com cuidado: evite as não informativas (por exemplo, vetor) e prefira as que já são usadas por outras pessoas (consulte o site do complemento)

• adicione um ícone adequado, não deixe o ícone padrão; consulte a interface QGIS para obter uma sugestão do estilo a ser usado

16.5.2. Código e ajuda

• não inclua arquivo gerado (ui_*.py, resources_rc.py, arquivos de ajuda gerados…) e coisas inúteis (por exemplo, .gitignore) no repositório

• adicione o plug-in ao menu apropriado (Vetor, Raster, Web, Banco de dados)

• quando apropriado (complementos que executam análises), considere adicionar o complemento como um subcomplemento da estrutura de Processar: isso permitirá que os usuários o executem em lote, integrem-no em fluxos de trabalho mais complexos e não necessitem projetar uma interface

• inclua pelo menos documentação mínima e, se útil para testar e entender, dados de amostra.

16.5.3. Repositório Oficial de complementos Python

Você pode encontrar o repositório oficial de complementos Python em https://plugins.qgis.org/.

Para usar o repositório oficial, você deve obter um ID OSGEO no portal web da OSGEO.

Depois de fazer o upload do seu complemento, ele será aprovado por um membro da equipe e você será notificado.

TODO:

Insira um link para o documento de governança

16.5.3.1. Permissões

Essas regras foram implementadas no repositório oficial de complementos:

• todo usuário registrado pode adicionar um novo complemento

• os usuários da equipe podem aprovar ou desaprovar todas as versões do complemento

• usuários com a permissão especial plugins.can_approve obtêm as versões que eles enviam automaticamente aprovadas

• usuários com a permissão especial plugins.can_approve podem aprovar versões enviadas por outros, desde que estejam na lista dos proprietários do complemento

• um complemento específico pode ser excluído e editado apenas por usuários da equipe e por seus proprietários

• se um usuário sem a permissão plugins.can_approve carrega uma nova versão, a versão do complemento é automaticamente não aprovada.

16.5.3.2. Gerenciamento de confiança

Os membros da equipe podem conceder confiança aos criadores de complementos selecionados, configurando a permissão plugins.can_approve através do aplicativo front-end.

A visualização de detalhes do complemento oferece links diretos para fornecer confiança ao criador ou ao proprietário do complemento.

16.5.3.3. Validação

Os metadados do complemento são importados e validados automaticamente do pacote compactado quando o upload é feito.

Aqui estão algumas regras de validação que você deve saber quando deseja fazer upload de um complemento no repositório oficial:

1. o nome da pasta principal que contém o complemento deve conter apenas caracteres ASCII (A-Z e a-z), dígitos e os caracteres sublinhados (_) e menos (-), também não pode começar com um dígito

2. metadata.txt é necessário

3. todos os metadados necessários, listados em metadata table devem estar presentes

4. o campo de metadados da versão deve ser exclusivo

16.5.3.4. Estrutura do complemento

Seguindo as regras de validação, o pacote compactado (.zip) do seu complemento deve ter uma estrutura específica para validar como um complemento funcional. Como o complemento será descompactado na pasta de complementos dos usuários, ele deve ter seu próprio diretório dentro do arquivo .zip para não interferir com outros complementos. Os arquivos obrigatórios são: metadata.txt e __init__.py. Mas seria bom ter um README e, é claro, um ícone para representar o complemento (resources.qrc). A seguir, é apresentado um exemplo de como um complemento.zip deve se parecer.

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