Guia de Contribuição

Como contribuir para o plugin WordPress middag-account.

Estratégia de Branches

Branch	Propósito
main	Código pronto para produção. Branch protegida.
develop	Branch de integração para o próximo release.
Feature	feat/{domain}-{description} a partir de develop.
Fix	fix/{domain}-{description} a partir de develop.
Hotfix	hotfix/{description} a partir de main (apenas críticos).

Fluxo de Release

feature branch -> PR -> develop -> PR -> main -> tag -> release

Tags disparam o pipeline de CI/CD que produz um ZIP distribuível.

Conventional Commits

Todas as mensagens de commit devem seguir a especificação Conventional Commits:

feat(entitlement): add auto-provisioning from paid quotes
fix(auth): validate token expiration before refresh
docs(api): update organization endpoint schemas
chore(deps): upgrade symfony/dependency-injection to 7.4.1
refactor(quote): extract status transition logic to enum
test(collaborator): add permission scope unit tests

Prefixo	Quando Usar
feat:	Nova funcionalidade ou capacidade
fix:	Correção de bug
docs:	Alterações apenas em documentação
chore:	Build, CI, atualização de dependências
refactor:	Reestruturação de código sem mudança de comportamento
test:	Adição ou atualização de testes
style:	Apenas estilo / formatação de código

Inclua o escopo do domínio entre parênteses quando aplicável: feat(quote):, fix(auth):.

Checklist de PR

Antes de enviar um pull request, verifique:

• [ ] A lógica de domínio não tem nenhuma importação do WordPress (src/Domain/ apenas)
• [ ] Injeção de construtor utilizada -- sem chamadas estáticas a serviços
• [ ] Classes de hook implementam HookInterface com register()
• [ ] Rotas REST possuem permission_callback em todo endpoint
• [ ] Input é sanitizado (sanitize_text_field, absint, sanitize_email)
• [ ] Output é escapado (esc_html, esc_attr, esc_url)
• [ ] O limite organizacional é aplicado nas queries
• [ ] Todas as strings voltadas ao usuário utilizam __() com text domain middag-account
• [ ] Testes unitários cobrem a lógica de domínio (meta: 90%+ para Domain/)
• [ ] composer check passa (style + rector + phpstan)
• [ ] Testes de integração cobrem endpoints REST, se aplicável

Padrões de Código

PHP

• PHP 8.4+ com tipagem estrita em todos os arquivos
• Autoloading PSR-4 sob o namespace Middag\Account\
• PHP-CS-Fixer aplica o estilo de código (execute composer fix para correção automática)
• Rector moderniza padrões de código
• PHPStan nível 6+ para análise estática

Convenções de Nomenclatura

Elemento	Convenção	Exemplo
Classe Entity	{Domain}Entity	OrganizationEntity
Classe Service	{Domain}Service	EntitlementService
Repository	{Domain}RepositoryInterface	QuoteRepositoryInterface
Classe Hook	{Domain}Hooks	EntitlementHooks
Controller	{Domain}Controller	OrderController
Page controller	{Domain}PageController	InvoicePageController
Enum de status	{Domain}Status	ContractStatus
Slug de CPT	middag_{domain}	middag_entitlement
Nome de hook	middag/{domain}/{event}	middag/quote/paid

Nomenclatura de Testes

Tipo	Padrão de Caminho
Unitário	tests/Unit/{mirrored-src-path}/{ClassName}Test.php
Integração	tests/Integration/{Feature}/{FeatureName}Test.php

Ordem de Implementação de Features

Ao adicionar um novo domínio ou funcionalidade, siga esta sequência:

1. Entidade de domínio + enum de status (PHP puro)
2. Interface de repositório (Domain/) e depois implementação (WordPress/)
3. Camada de serviço (Domain/)
4. Classes de hook (WordPress/Hook/)
5. REST controller (Api/)
6. Camada de integração (se serviços externos estiverem envolvidos)
7. Inertia page controller (UI/) + páginas React
8. Testes -- unitários + integração

Relacionados

• Desenvolvimento Local -- Setup e ferramentas
• Visão Geral da Arquitetura -- Estrutura do projeto