From 135b621576be5e876e04e0000dfa19b7111d8108 Mon Sep 17 00:00:00 2001 From: Rodolpho Lopes Date: Thu, 11 Jun 2026 18:14:56 +0000 Subject: [PATCH] kb: KB-PLUGIN-031 vira o processo OFICIAL de dev de plugins (5 passos + regra de ouro) 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 --- index.json | 5 +- ...-PLUGIN-031-plugin-dev-workflow-runbook.md | 184 +++++++++++------- 2 files changed, 112 insertions(+), 77 deletions(-) diff --git a/index.json b/index.json index a7ba63e..549a08f 100755 --- a/index.json +++ b/index.json @@ -554,7 +554,7 @@ }, { "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", "tags": [ "runbook", @@ -564,7 +564,8 @@ "forgejo", "scaffold", "validation", - "console" + "console", + "processo-oficial" ], "status": "active", "severity": "high", diff --git a/records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md b/records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md index 634b75a..4759198 100644 --- a/records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md +++ b/records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md @@ -1,6 +1,6 @@ --- 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 tags: - runbook @@ -11,6 +11,7 @@ tags: - scaffold - validation - console + - processo-oficial status: active severity: high created_at: 2026-06-11 @@ -28,14 +29,38 @@ related_records: - 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 -desenvolvimento. A **publicação em produção** (Mindplace/licenciamento) é outro -processo — ver [KB-PLUGIN-013](KB-PLUGIN-013-mindplace-plugin-publication-runbook.md). +Processo padrão em 5 passos, do nascimento do plugin até a produção: + +``` +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). +## ⭐ 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 | 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) | | 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`) | -| Git de dev | Forgejo local — `git@192.168.100.101:administrador/.git` (remote `origin`) | -| Git de produção | Forgejo Mindtek — remote `production`, usado **só** na publicação | +| Knowledge-base | `/opt/projects/GLPI11/knowledge-base/` (repo no Forgejo dev) | +| Forgejo DEV | `git@192.168.100.101:administrador/.git` (remote `origin`) | +| Forgejo PROD | `servicedesk.mindtek.com.br/git/rodolpho.lopes/` (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, -hooks, constantes): +```bash +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 && cd +git init && git branch -M main +``` + +Estrutura mínima obrigatória (a chave/diretório define TUDO — funções, hooks, +constantes): ``` / ├── setup.php # plugin_init_, plugin_version_ + 4 callbacks ├── hook.php # install/uninstall e demais hooks ├── 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 ├── LICENSE # GPL-3.0-or-later (compatível com o GLPI) └── .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]). - [ ] `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á. +- [ ] Ownership: `chown -R www-data:www-data ` + `git config --global + --add safe.directory ` (git roda como root, arquivos são www-data). -## Fase 2 — Repositório no Forgejo local - -Criar o repo via API (ou UI em `http://192.168.100.101:3000`): - -```bash -curl -s -u 'administrador:' -X POST \ - http://192.168.100.101:3000/api/v1/user/repos \ - -H 'Content-Type: application/json' \ - -d '{"name":"","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 " 0.1.0: scaffold" -git remote add origin git@192.168.100.101:administrador/.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/.git -git config --global --add safe.directory \ - /opt/projects/GLPI11/docker/glpi/plugins/ -chown -R www-data:www-data -``` - -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) +Instalação e ativação **sempre via console** (erros legíveis; a UI só mostra +falha genérica): ```bash 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 ' ``` -Esperado: status **Habilitado**. O console dá erros legíveis; a UI só mostra -falha genérica. +## Passo 3 — Push para o Forgejo DEV -## 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:' -X POST \ + http://192.168.100.101:3000/api/v1/user/repos \ + -H 'Content-Type: application/json' \ + -d '{"name":"","private":true,"default_branch":"main"}' +``` + +```bash +git remote add origin git@192.168.100.101:administrador/.git +git add -A && git commit -m " 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 mais o core (classes como `RuleAsset` ficam indisponíveis). O bootstrap correto @@ -139,41 +168,46 @@ $_SESSION['glpiactive_entity'] = 0; $_SESSION['glpiactiveprofile']['interface'] = 'central'; ``` -Padrão do teste: criar massa de dados de teste com prefixo `TEST` → -exercitar os cenários → **deletar tudo com purge no final**. Executar: +Padrão do teste: criar massa de dados com prefixo `TEST` → exercitar os +cenários → **deletar tudo com purge no final**. Executar: ```bash -scp test_.php root@192.168.100.49:/tmp/ -ssh root@192.168.100.49 'docker cp /tmp/test_.php glpi11-app:/tmp/ && - docker exec glpi11-app php /tmp/test_.php' +docker cp test_.php glpi11-app:/tmp/ +docker exec glpi11-app php /tmp/test_.php ``` -Exemplo real completo: teste E2E do `assetinherit` (6 cenários, incluindo -descoberta de comportamento que virou documentação — critério `PATTERN_EXISTS` -não casa com `users_id = 0`). +Exemplo real: teste E2E do `assetinherit` (6 cenários; a homologação revelou +comportamento que virou documentação — `PATTERN_EXISTS` não casa com +`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. -2. Editar in-place — GLPI é PHP, refresh no browser e a mudança aparece. -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). +**→ É aqui que se cumpre o item 3 da Regra de ouro: escrever o(s) novo(s) KB(s) +com o que o desenvolvimento ensinou.** -## 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, -release ZIP com wrapper directory [KB-PLUGIN-018], catálogo Mindplace, -serial do cliente). +Somente após homologação: + +```bash +git remote add production https://servicedesk.mindtek.com.br/git/rodolpho.lopes/.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 -Ao criar/depurar plugin novo no ambiente dev, seguir este runbook na ordem. -Antes de diagnosticar erro funcional, validar Fases 3-4 (mount, ownership, -instalação via console). Para testes E2E em CLI, usar SEMPRE o bootstrap do -Kernel (Fase 5), nunca `inc/includes.php`. +Ao criar/depurar plugin, seguir os 5 passos na ordem e a Regra de ouro sempre: +KB primeiro, core do GLPI na ausência de KB, novo KB após validação. Antes de +diagnosticar erro funcional, validar mount/ownership/instalação via console +(Passo 2). Para testes E2E em CLI, usar SEMPRE o bootstrap do Kernel (Passo 4), +nunca `inc/includes.php`. ## Classificação -- Tipo: Runbook operacional de desenvolvimento. +- Tipo: Runbook operacional — processo oficial de desenvolvimento. - Reutilização: obrigatória para todo plugin novo.