rodolpho.lopes/knowledge-base
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

kb: KB-PLUGIN-031 vira o processo OFICIAL de dev de plugins (5 passos + regra de ouro)

Browse source 
Processo definido: (1) acessar DEV CT100, (2) criar plugin direto em
plugins/ para dev+validacao conjunta via interface, (3) push Forgejo DEV,
(4) homologar, (5) push Forgejo PROD.
Regra de ouro: knowledge-base como fonte primaria; core do GLPI na
ausencia de KB; novo KB apos teste validado.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Rodolpho Lopes 2026-06-11 18:14:56 +00:00
parent 200cd6c2ce
commit 135b621576
2 changed files with 112 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
index.json
View file

@ -554,7 +554,7 @@
}, },
{ {
"id": "KB-PLUGIN-031", "id": "KB-PLUGIN-031",
"title": "\"Runbook — Workflow de desenvolvimento e deploy DEV de plugins GLPI\"", "title": "\"Runbook — Processo oficial de desenvolvimento de plugins GLPI (DEV → homologação → PROD)\"",
"domain": "plugin-dev", "domain": "plugin-dev",
"tags": [ "tags": [
"runbook", "runbook",
@ -564,7 +564,8 @@
"forgejo", "forgejo",
"scaffold", "scaffold",
"validation", "validation",
"console" "console",
"processo-oficial"
], ],
"status": "active", "status": "active",
"severity": "high", "severity": "high",

184
records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md
View file

@ -1,6 +1,6 @@
--- ---
id: KB-PLUGIN-031 id: KB-PLUGIN-031
title: "Runbook — Workflow de desenvolvimento e deploy DEV de plugins GLPI" title: "Runbook — Processo oficial de desenvolvimento de plugins GLPI (DEV → homologação → PROD)"
domain: plugin-dev domain: plugin-dev
tags: tags:
- runbook - runbook
@ -11,6 +11,7 @@ tags:
- scaffold - scaffold
- validation - validation
- console - console
- processo-oficial
status: active status: active
severity: high severity: high
created_at: 2026-06-11 created_at: 2026-06-11
@ -28,14 +29,38 @@ related_records:
- KB-PLUGIN-027 - KB-PLUGIN-027
--- ---
# Runbook — Workflow de desenvolvimento e deploy DEV de plugins GLPI # Runbook — Processo oficial de desenvolvimento de plugins GLPI
Procedimento padrão do nascimento de um plugin até sua validação no GLPI de Processo padrão em 5 passos, do nascimento do plugin até a produção:
desenvolvimento. A **publicação em produção** (Mindplace/licenciamento) é outro
processo — ver [KB-PLUGIN-013](KB-PLUGIN-013-mindplace-plugin-publication-runbook.md). ```
1. Acessar o ambiente DEV (CT 100)
2. Criar o diretório do plugin direto em .../plugins/ ← dev e validação
acontecem juntos, pela interface do GLPI dev
3. Push para o Forgejo DEV (origin)
4. Homologar (testes funcionais + E2E validados)
5. Deploy: push para o Forgejo de PROD (remote production)
```
A publicação completa em PROD (Mindplace, licenciamento, release ZIP) é
detalhada em [KB-PLUGIN-013](KB-PLUGIN-013-mindplace-plugin-publication-runbook.md)
e [KB-PLUGIN-027](KB-PLUGIN-027-mcprotocol-dev-prod-release-flow.md).
Primeiro plugin a seguir este fluxo de ponta a ponta: `assetinherit` (2026-06-11). Primeiro plugin a seguir este fluxo de ponta a ponta: `assetinherit` (2026-06-11).
## ⭐ Regra de ouro — protocolo de conhecimento
Durante TODO o processo de desenvolvimento:
1. **Knowledge-base é a fonte primária.** Antes de implementar ou diagnosticar
qualquer coisa, consultar `index.json` e os records relevantes desta base.
2. **Na ausência de dado relevante, estudar o core do GLPI** (código-fonte em
`/var/www/glpi/src/` no container, ou clone do branch `11.0/bugfixes`).
Não confiar em memória/suposição sobre comportamento do GLPI — ler o código.
3. **Após o teste validado, escrever um novo KB** com o que foi aprendido,
para que o próximo desenvolvimento seja mais fácil. Rodar `make kb-fix`
e `make kb-check`, commitar e push.
## Mapa do ambiente ## Mapa do ambiente
| Componente | Onde | | Componente | Onde |
@ -43,20 +68,40 @@ Primeiro plugin a seguir este fluxo de ponta a ponta: `assetinherit` (2026-06-11
| Servidor dev (docker) | CT 100 — `root@192.168.100.49` (SSH key do Mac já cadastrada) | | Servidor dev (docker) | CT 100 — `root@192.168.100.49` (SSH key do Mac já cadastrada) |
| Diretório de plugins | `/opt/projects/GLPI11/docker/glpi/plugins/` (bind → `/var/www/glpi/plugins`, ver [KB-INFRA-001]) | | Diretório de plugins | `/opt/projects/GLPI11/docker/glpi/plugins/` (bind → `/var/www/glpi/plugins`, ver [KB-INFRA-001]) |
| Container GLPI | `glpi11-app` (GLPI dev em `http://192.168.100.49:8081`) | | Container GLPI | `glpi11-app` (GLPI dev em `http://192.168.100.49:8081`) |
| Git de dev | Forgejo local — `git@192.168.100.101:administrador/<plugin>.git` (remote `origin`) | | Knowledge-base | `/opt/projects/GLPI11/knowledge-base/` (repo no Forgejo dev) |
| Git de produção | Forgejo Mindtek — remote `production`, usado **só** na publicação | | Forgejo DEV | `git@192.168.100.101:administrador/<plugin>.git` (remote `origin`) |
| Forgejo PROD | `servicedesk.mindtek.com.br/git/rodolpho.lopes/<plugin>` (remote `production`) |
## Fase 1 — Scaffold do plugin ## Passo 1 — Acessar o ambiente DEV
Estrutura mínima obrigatória (a chave/diretório do plugin define TUDO — funções, ```bash
hooks, constantes): ssh root@192.168.100.49
cd /opt/projects/GLPI11/docker/glpi/plugins
```
Ou via IDE no Mac: Remote SSH em `root@192.168.100.49`, abrir a pasta do plugin.
O bind mount entrega qualquer mudança ao container na hora — GLPI é PHP, lê do
disco a cada request: salvar arquivo + refresh no browser, sem recriar container.
## Passo 2 — Criar o plugin direto em plugins/
O diretório nasce no servidor dev, assim humano e agente trabalham e validam
juntos pela interface do GLPI dev desde o primeiro minuto.
```bash
mkdir <key> && cd <key>
git init && git branch -M main
```
Estrutura mínima obrigatória (a chave/diretório define TUDO — funções, hooks,
constantes):
``` ```
<key>/ <key>/
├── setup.php # plugin_init_<key>, plugin_version_<key> + 4 callbacks ├── setup.php # plugin_init_<key>, plugin_version_<key> + 4 callbacks
├── hook.php # install/uninstall e demais hooks ├── hook.php # install/uninstall e demais hooks
├── logo.png # PNG 128x128 na raiz — obrigatório [KB-INFRA-002] ├── logo.png # PNG 128x128 na raiz — obrigatório [KB-INFRA-002]
├── README.md # dor que resolve, como funciona, instalação, configuração ├── README.md # dor que resolve, como funciona, instalação, CONFIGURAÇÃO passo a passo
├── CHANGELOG.md # Keep a Changelog ├── CHANGELOG.md # Keep a Changelog
├── LICENSE # GPL-3.0-or-later (compatível com o GLPI) ├── LICENSE # GPL-3.0-or-later (compatível com o GLPI)
└── .gitignore # padrão de plugins [KB-PLUGIN-013] └── .gitignore # padrão de plugins [KB-PLUGIN-013]
@ -70,45 +115,11 @@ Checklist de armadilhas conhecidas:
(= nome do diretório). Variações falham em silêncio ([KB-PLUGIN-004]). (= nome do diretório). Variações falham em silêncio ([KB-PLUGIN-004]).
- [ ] `logo.png` é PNG real (SVG renomeado não funciona) ([KB-INFRA-002]). - [ ] `logo.png` é PNG real (SVG renomeado não funciona) ([KB-INFRA-002]).
- [ ] `version` no `setup.php` em SemVer — o release de produção lê de lá. - [ ] `version` no `setup.php` em SemVer — o release de produção lê de lá.
- [ ] Ownership: `chown -R www-data:www-data <key>` + `git config --global
--add safe.directory <path>` (git roda como root, arquivos são www-data).
## Fase 2 — Repositório no Forgejo local Instalação e ativação **sempre via console** (erros legíveis; a UI só mostra
falha genérica):
Criar o repo via API (ou UI em `http://192.168.100.101:3000`):
```bash
curl -s -u 'administrador:<senha>' -X POST \
http://192.168.100.101:3000/api/v1/user/repos \
-H 'Content-Type: application/json' \
-d '{"name":"<key>","private":true,"default_branch":"main"}'
```
No diretório do plugin (na máquina de dev):
```bash
git init && git branch -M main
git add -A && git commit -m "<key> 0.1.0: scaffold"
git remote add origin git@192.168.100.101:administrador/<key>.git
git push -u origin main
```
Convenção de remotes: `origin` = Forgejo local (push contínuo de dev);
`production` = Forgejo Mindtek (adicionado apenas na publicação, [KB-PLUGIN-013]).
## Fase 3 — Deploy no servidor dev
```bash
ssh root@192.168.100.49
cd /opt/projects/GLPI11/docker/glpi/plugins
git clone git@192.168.100.101:administrador/<key>.git
git config --global --add safe.directory \
/opt/projects/GLPI11/docker/glpi/plugins/<key>
chown -R www-data:www-data <key>
```
O bind mount entrega o plugin no container instantaneamente — **não** precisa
recriar o container.
## Fase 4 — Instalação e ativação (sempre via console)
```bash ```bash
docker exec glpi11-app sh -c ' docker exec glpi11-app sh -c '
@ -119,10 +130,28 @@ docker exec glpi11-app sh -c '
php /var/www/glpi/bin/console plugin:list | grep <key>' php /var/www/glpi/bin/console plugin:list | grep <key>'
``` ```
Esperado: status **Habilitado**. O console dá erros legíveis; a UI só mostra ## Passo 3 — Push para o Forgejo DEV
falha genérica.
## Fase 5 — Validação funcional (teste E2E em CLI) Criar o repo (API ou UI em `http://192.168.100.101:3000`):
```bash
curl -s -u 'administrador:<senha>' -X POST \
http://192.168.100.101:3000/api/v1/user/repos \
-H 'Content-Type: application/json' \
-d '{"name":"<key>","private":true,"default_branch":"main"}'
```
```bash
git remote add origin git@192.168.100.101:administrador/<key>.git
git add -A && git commit -m "<key> 0.1.0: scaffold"
git push -u origin main
```
Durante o desenvolvimento, commit + push contínuos para `origin`.
## Passo 4 — Homologar
Validação funcional pela interface do GLPI dev **e** teste E2E automatizado em CLI.
⚠️ **Gotcha do GLPI 11:** em CLI, `include 'inc/includes.php'` **não** carrega ⚠️ **Gotcha do GLPI 11:** em CLI, `include 'inc/includes.php'` **não** carrega
mais o core (classes como `RuleAsset` ficam indisponíveis). O bootstrap correto mais o core (classes como `RuleAsset` ficam indisponíveis). O bootstrap correto
@ -139,41 +168,46 @@ $_SESSION['glpiactive_entity'] = 0;
$_SESSION['glpiactiveprofile']['interface'] = 'central'; $_SESSION['glpiactiveprofile']['interface'] = 'central';
``` ```
Padrão do teste: criar massa de dados de teste com prefixo `TEST` → Padrão do teste: criar massa de dados com prefixo `TEST` → exercitar os
exercitar os cenários → **deletar tudo com purge no final**. Executar: cenários → **deletar tudo com purge no final**. Executar:
```bash ```bash
scp test_<key>.php root@192.168.100.49:/tmp/ docker cp test_<key>.php glpi11-app:/tmp/
ssh root@192.168.100.49 'docker cp /tmp/test_<key>.php glpi11-app:/tmp/ && docker exec glpi11-app php /tmp/test_<key>.php
docker exec glpi11-app php /tmp/test_<key>.php'
``` ```
Exemplo real completo: teste E2E do `assetinherit` (6 cenários, incluindo Exemplo real: teste E2E do `assetinherit` (6 cenários; a homologação revelou
descoberta de comportamento que virou documentação — critério `PATTERN_EXISTS` comportamento que virou documentação — `PATTERN_EXISTS` não casa com
não casa com `users_id = 0`). `users_id = 0`, exigindo regra complementar de desvínculo).
## Fase 6 — Ciclo de iteração Homologado = todos os cenários OK + README com passo a passo de configuração
conferido contra o comportamento real.
1. IDE no Mac → Remote SSH em `root@192.168.100.49`, pasta do plugin. **→ É aqui que se cumpre o item 3 da Regra de ouro: escrever o(s) novo(s) KB(s)
2. Editar in-place — GLPI é PHP, refresh no browser e a mudança aparece. com o que o desenvolvimento ensinou.**
3. `git add . && git commit && git push` → Forgejo local (`origin`).
4. Mudanças feitas no Mac: `git push origin` no Mac + `git pull` no CT 100
(lembrar `chown -R www-data:www-data` se criar arquivos novos como root).
## Fase 7 — Promoção para produção (fora deste runbook) ## Passo 5 — Deploy para o Forgejo de PROD
Quando validado no dev: seguir [KB-PLUGIN-013] (kill switch de licença, Somente após homologação:
release ZIP com wrapper directory [KB-PLUGIN-018], catálogo Mindplace,
serial do cliente). ```bash
git remote add production https://servicedesk.mindtek.com.br/git/rodolpho.lopes/<key>.git
git push production main
```
Publicação no marketplace (release ZIP com wrapper [KB-PLUGIN-018], catálogo
Mindplace, kill switch de licença, serial do cliente): seguir
[KB-PLUGIN-013]. Topologia dev→prod detalhada: [KB-PLUGIN-027].
## Regra para agentes ## Regra para agentes
Ao criar/depurar plugin novo no ambiente dev, seguir este runbook na ordem. Ao criar/depurar plugin, seguir os 5 passos na ordem e a Regra de ouro sempre:
Antes de diagnosticar erro funcional, validar Fases 3-4 (mount, ownership, KB primeiro, core do GLPI na ausência de KB, novo KB após validação. Antes de
instalação via console). Para testes E2E em CLI, usar SEMPRE o bootstrap do diagnosticar erro funcional, validar mount/ownership/instalação via console
Kernel (Fase 5), nunca `inc/includes.php`. (Passo 2). Para testes E2E em CLI, usar SEMPRE o bootstrap do Kernel (Passo 4),
nunca `inc/includes.php`.
## Classificação ## Classificação
- Tipo: Runbook operacional de desenvolvimento. - Tipo: Runbook operacional — processo oficial de desenvolvimento.
- Reutilização: obrigatória para todo plugin novo. - Reutilização: obrigatória para todo plugin novo.