deskcomm-contribuir

# Contribuir para o DeskcommCRM sem retrabalho Quem contribui aqui quase nunca erra por falta de capacidade — erra por não saber a régua. A régua existe, mas está espalhada em três documentos (`CLAUDE.md`, `CONTRIBUTING.md` e o procedimento de triagem, com mais de 100 KB) e é aplicada **depois** do PR, por quem mantém. Este guia aplica a mesma régua **antes**, do seu lado, para o PR chegar pronto. Taxa histórica de recusa de PR de fork: zero. O que trava é retrabalho — e retrabalho se evita medindo. ## Como você age - **Aconselha, não bloqueia.** Você mede e mostra; só os hooks de git bloqueiam, e só o que é irreversível (push na `main`, migration sem a tripla). Uma pessoa que quer seguir mesmo assim segue — sabendo o que vai acontecer na triagem. - **Mede na fonte, nunca copia número.** A lista de checks obrigatórios, quantas specs rodam e o que o CI cobre mudam toda semana; cada afirmação vem com o comando que a produziu. - **Declara o que não mediu.** Um PR que diz "não rodei o e2e porque não tenho Docker" é melhor que um que marca tudo. O mantenedor prova o que ficou faltando; a régua pública é essa. - **Sabota antes de dizer "testado".** Teste que não fica vermelho quando o conserto sai não guarda nada. ## Passo 0 — quem está contribuindo Este passo vem **antes** de trazer a `main` (Passo 1), então não conte com o script estar no clone: um fork anterior a 2026-09-10 ainda não o tem, e o guia pode ter vindo da instalação global. O comando abaixo procura o script na raiz do clone (vale de qualquer subpasta dele) e, se não achar, nas três pastas globais em que o `instalar-guias.sh` põe os guias. Cole como está, de onde você estiver: ```bash r="$(git rev-parse --show-toplevel 2>/dev/null)"; s="" for g in ${r:+"$r/.agents/skills"} ~/.claude/skills ~/.agents/skills ~/.gemini/config/skills; do [ -f "$g/deskcomm-contribuir/scripts/quem-sou.sh" ] && { s="$g/deskcomm-contribuir/scripts/quem-sou.sh"; break; } done if [ -n "$s" ]; then bash "$s"; else echo "NÃO MEDIDO — não achei o quem-sou.sh ${r:+no clone $r }nem nas pastas globais dos guias." >&2 echo "Instale os guias pelo comando de uma linha do README (https://github.com/melgarafael/DeskcommCRM#readme) e rode de novo." >&2 false fi ``` A resposta vem da pasta **onde você rodou**, não de onde o script mora: fora de um clone ela é `contribuidor — fora de um clone git`, e se afina sozinha assim que o terminal estiver dentro do clone. A resposta decide o resto do guia, e são três: - Começa com `mantenedor`: este guia fica quieto — o mantenedor tem o próprio ritual (triagem, gov-loop) e hooks próprios em `loop/hooks`. Só siga se a pessoa pedir por nome. - Começa com `contribuidor`: siga. O script diz **por quê** (e-mail do git no `.mailmap`, conta do `gh`, o `origin` ser fork). - Começa com `NÃO MEDIDO` (e o bloco sai com erro): o script não está nem no clone nem nas pastas globais — um fork anterior a 2026-09-10 sem a instalação global, ou um terminal fora de clone sem ela. Ninguém foi classificado: não trate a pessoa como mantenedor nem como contribuidor por essa saída. Instale os guias pelo comando de uma linha do README, que a própria saída aponta, e rode este passo de novo — vale de qualquer pasta, inclusive num fork cujo `main` ainda não tem o script. ## Passo 1 — a âncora: `origin/main`, nunca o disco ```bash git fetch origin MAIN=$(git rev-parse --short origin/main); echo "main=$MAIN" B=$(git merge-base origin/main HEAD) echo "atraso=$(git rev-list --count $B..origin/main) proprios=$(git rev-list --count $B..HEAD)" comm -12 <(git diff --name-only $B origin/main | sort) <(git diff --name-only $B HEAD | sort) # sobreposição ``` - **Branch nova** nasce de `origin/main` **deste** repositório, com nome (`fix/o-que-conserta`), nunca do `main` do fork: o `main` do fork carrega as personalizações da instalação da pessoa (marca, `.env`, config) e um PR aberto dali propõe tudo isso ao produto inteiro — foi medido, sete arquivos com a marca de um cliente mergeando sem conflito (PR #465). - **Atraso > 0** → traga a `main` para dentro: `git merge --ff-only origin/main` se `proprios=0`, senão `git merge origin/main`. Nunca `reset --hard` nem `push --force`: apaga trabalho. Conflito se resolve lendo os dois lados (ver `references/pre-voo.md`, seção "conflito"). - **Sobreposição** (arquivos que a `main` também mudou) é onde nasce conflito: mescle cedo, não na hora do PR. - O CI testa **a branch**, não o resultado do merge (`strict=false` na proteção da `main`): verde na branch atrasada não prova nada sobre o merge. ## Passo 2 — arme os hooks (uma vez por clone) ```bash bash .agents/skills/deskcomm-contribuir/scripts/armar-hooks.sh ``` Três guardas, e só isso: `pre-commit` reprova migration nova sem apêndice no `baseline.sql` e sem linha no `MANIFEST.md` no mesmo commit, e número (`NNNN`) ou timestamp já usado na `origin/main` ou em branch local; `pre-push` reprova push na `main`; e os dois avisam (sem bloquear) quando o commit está assinado como `root@…` ou sem e-mail — trabalho assinado assim não aparece no perfil do GitHub de quem fez. O mantenedor roda hooks próprios (`loop/hooks`); o script recusa sobrescrevê-los. ## Passo 3 — antes de codar - Leia a doutrina do que vai tocar: a skill `deskcomm-doutrina` aponta as três regras que mais custam (multi-tenancy com RLS, tripla de migration, nenhuma feature nomeia provider) e manda abrir o `CLAUDE.md` da `origin/main` — não de um resumo. - Issue: comente "pego esta" antes de codar; um mantenedor atribui. Sem resposta em 48 h, comece e diga no PR. Issue com pessoa atribuída não se duplica. - Peça de sistema (lead, agente, follow-up, tela, worker, métrica)? Carregue a skill `sistema-vivo` — o Living System Checklist é item do Definition of Done. ## Passo 4 — o pré-voo, antes de abrir o PR ```bash bash .agents/skills/deskcomm-contribuir/scripts/pre-voo.sh ``` Ele imprime, medido e com o comando ao lado, o que o mantenedor vai medir: atraso e sobreposição, arquivos fora do produto no diff (marca, `.env`, config do fork), segredo no diff, `console.log` novo (o lint só avisa), migration nova e a tripla, seção de versão escrita à mão no `CHANGELOG.md` (bloqueador — o corte de release é automático), fragmento em `.changes/`, documento de autoridade tocado, identidade dos commits. A leitura de cada item e o que fazer: `references/pre-voo.md`. Depois, os gates que o CI roda sozinho — rode a suíte, não os gates que você lembra: ```bash rm -f tsconfig*.tsbuildinfo; pnpm typecheck; echo exit=$? pnpm lint; echo exit=$? pnpm lint:channels; echo exit=$? pnpm test:unit > /tmp/vt.log 2>&1; echo exit=$?; grep -aE "Test Files|Tests " /tmp/vt.log | tail -2 pnpm test:shell; echo exit=$? # se tocou hostgator-setup-kit/, Dockerfile* ou compose pnpm test:db; echo exit=$? # se tocou schema/RLS/RBAC (precisa de Docker) pnpm build; echo exit=$? ``` `test:unit` sem caminho: o script alcança o repositório inteiro (testes ao lado do código inclusive); `vitest run tests/unit` é um verde menor. Não corte a saída com `tail` — o rodapé é a autoridade e os nomes dos arquivos vermelhos são o único dado que permite reconciliar. ## Passo 5 — o teste que falta, e a sabotagem Mudou comportamento? Então existe um teste que fica vermelho sem a sua mudança. Se não existe, escreva. Depois **commite** e sabote: reverta só a linha do conserto (não o commit), preveja quantos casos vão cair (e quais), rode, confira a contagem, restaure. "1 vermelho de N, o previsto" vai no corpo do PR. Sabotar antes de commitar já custou trabalho perdido aqui mais de uma vez. ## Passo 6 — prova em tela (se tocou UI ou fluxo de usuário) A doutrina do repo: `curl` não prova experiência; Playwright dirigindo o front, num banco fresco do `baseline.sql`, com os envs opcionais **ausentes** (o estado real de uma instalação nova). A receita local inteira, na ordem, com o que precisa instalado: `references/receita-e2e-local.md`. Sem Docker ou sem tempo: mande o que conseguiu provar (unit + o que testou na mão, passo a passo) e diga que a prova de tela ficou com o mantenedor — é o combinado público, não uma falha. Spec nova entra em `SPECS_PARTE_N` do `.github/workflows/e2e.yml` (ou em `FORA_DO_CI` com o motivo escrito); o teste `tests/unit/e2e-cobertura-completa.test.ts` reprova spec órfã. ## Passo 7 — o fragmento de release (não o CHANGELOG) Mudou algo que quem opera uma VPS percebe? Escreva `.changes/<kebab>.md`: ```markdown --- impacto: capacidade_nova # nada_mudou | capacidade_nova | exige_acao secao: adicionado # adicionado | alterado | corrigido titulo: O que muda, na voz de quem usa --- Um parágrafo do ponto de vista do operador. Sem título, sem ⚠. Crédito: @seu-usuario. ``` `pnpm release:conferir` valida a forma. **Nunca** escreva `## [1.x.y]` no `CHANGELOG.md`: o corte de release é automático e uma seção à mão já quase publicou uma versão pelo merge de um PR. `exige_acao` só se o operador precisa fazer algo na VPS (variável nova obrigatória, por exemplo) — e aí o instalador precisa perguntar por ela. O texto do fragmento vira a nota pública da versão: a LP publica o `CHANGELOG.md` em [deskcomm.com.br/changelog](https://www.deskcomm.com.br/changelog), nos três idiomas. Escreva para quem nunca viu o código. **Mexeu num guia** (`.agents/skills/deskcomm-*`: nome, o que ele faz, como chamar)? Rode `pnpm skills:sync` e avise no PR que a página de guias da LP ([deskcomm.com.br/guias](https://www.deskcomm.com.br/guias), arquivo `conteudo/guias.ts` do repositório `deskcomm-site`) precisa acompanhar — senão ela passa a ensinar um guia que não existe. As duas páginas saem de um PR do `deskcomm-site`; um `404` nesses dois links quer dizer que ele ainda não entrou, não que você errou o caminho. ## Passo 8 — o PR - **Título** no imperativo, do ponto de vista de quem usa (`fix(agenda): a consulta remarcada não some do dia`), commits em conventional commits, PT-BR aceito. - **Corpo**: o que muda para quem usa; `Closes #N`; o que você mediu (comandos e saídas: o rodapé do `test:unit`, a sabotagem, a prova de tela); e um bloco **"O que NÃO medi"** — é o campo que separa medição de relato. - **Identidade**: `git log --format='%an <%ae>' origin/main..HEAD | sort -u` — se aparecer `root@…` ou um e-mail que não é da sua conta, o trabalho não aparece no seu perfil. Conserte antes do push (`git config user.email`, `git commit --amend --reset-author` nos seus commits). É também a identidade que a triagem põe como autor quando porta o seu trabalho do lado de cá. - **Edição por mantenedores**: com "Allow edits by maintainers" ligado (confira com `gh pr view <n> --json maintainerCanModify --jq .maintainerCanModify`), a triagem pode empurrar na sua branch um conserto ou o merge da `main`, avisando no PR antes. Antes de empurrar de novo, `git pull --no-rebase` — nunca `--force`. O que vai parecer erro depois de abrir — e não é — e como acompanhar o CI de verdade: `references/depois-do-pr.md`. Os erros mais frequentes de quem contribui, com o número do PR onde aconteceram: `references/erros-recorrentes.md`. ## O que você nunca faz - `git reset --hard`, `push --force`, `rebase` de commits já publicados, `stash pop` em worktree que não é seu (o stash é compartilhado entre worktrees e importa trabalho alheio). - Editar migration já aplicada — corrija com uma nova (forward-fix) e mais um apêndice. - Tocar em worktree com árvore suja que não é sua. - Trocar constante de marca, título de tela ou `.env` do produto para "a sua instalação" — isso vive no banco e na tela Configurações › Marca; no PR é vazamento. - Fechar o próprio PR por achar que "fez ruído". Três pessoas fizeram isso sem ter errado nada.