Guia de Contribuição

Obrigado por considerar contribuir com a documentação do Filament Core Suite! Este guia fornece instruções sobre como contribuir de forma eficaz.

📋 Antes de Começar

Este repositório segue padrões específicos documentados em Diretrizes para Agentes. Leia-as antes de fazer contribuições significativas.

🚀 Processo de Contribuição

1. Fork e Clone

# Fork o repositório no GitHub
git clone https://github.com/seu-usuario/filament-core-docs.git
cd filament-core-docs

2. Configurar Ambiente

# Instalar dependências
npm install

# Iniciar servidor de desenvolvimento
npm run docs:dev

O servidor estará disponível em http://localhost:5173

3. Fazer Alterações

• Crie uma branch descritiva: git checkout -b docs/adicionar-guia-webhooks
• Faça suas alterações nos arquivos Markdown em docs/
• Siga as convenções de escrita descritas abaixo

4. Validar Alterações

Antes de criar um Pull Request, execute:

# Lint de formatação Markdown
npm run lint:md

# Verificar links quebrados
npm run lint:links

# Build do VitePress
npm run docs:build

# Ou execute tudo de uma vez
npm run lint

IMPORTANTE: Todos os lints devem passar sem erros.

5. Commit

Use Conventional Commits:

# Exemplos de boas mensagens
git commit -m "docs: adicionar guia de webhooks para communications"
git commit -m "docs: corrigir links quebrados em people/overview"
git commit -m "fix: corrigir configuração do VitePress"

Tipos de commit:

• docs: - Adições ou alterações de documentação
• fix: - Correções de bugs ou links quebrados
• chore: - Mudanças em ferramentas, configurações, dependências
• ci: - Mudanças em workflows CI/CD

6. Push e Pull Request

# Push para seu fork
git push origin docs/adicionar-guia-webhooks

Abra um Pull Request no GitHub com:

• Título descritivo seguindo Conventional Commits
• Descrição detalhada do que foi alterado e por quê
• Checklist de verificação (veja template abaixo)
• Screenshots se aplicável (diagramas, mudanças visuais)

📝 Convenções de Escrita

Estrutura de Arquivos

• Novos módulos: docs/<modulo>/overview.md
• Guias específicos: docs/<modulo>/nome-do-guia.md
• Diagramas reutilizáveis: docs/snippets/
• Exemplos práticos: docs/<modulo>/examples.md

Nomenclatura

• Arquivos: minúsculas com hífens (invoice-pdf-flow.md)
• Diretórios: singular (docs/invoice, não docs/invoices)
• Headings: ATX style (#, ##, ###)

Formatação

• Idioma: Português do Brasil
• Voz: Ativa e concisa
• Linhas: Máximo ~100 caracteres para facilitar revisão
• Code blocks: Sempre especifique a linguagem (```php, ```bash, ```text)
• Diagramas: Use blocos de texto monospace (```text)

Exemplos de Código

// Bom: código ilustrativo e claro
class CpfValidator implements DocumentValidatorContract
{
    public function validate(string $document): bool
    {
        // Remove caracteres não numéricos
        $cpf = preg_replace('/[^0-9]/', '', $document);
        
        // Validação...
        return $this->validateChecksum($cpf);
    }
}

Nota: Código de exemplo deve ser ilustrativo, não implementação real.

✅ Checklist para Pull Requests

Copie e cole no seu PR:

## Checklist

- [ ] Li as [Diretrizes para Agentes](/agents) e segui as convenções
- [ ] Executei `npm run lint` sem erros
- [ ] Executei `npm run docs:build` com sucesso
- [ ] Testei localmente com `npm run docs:dev`
- [ ] Commit messages seguem Conventional Commits
- [ ] Adicionei links para documentação relacionada quando aplicável
- [ ] Verifiquei que não há links quebrados
- [ ] Screenshots incluídos (se mudanças visuais)

## Descrição

<!-- Descreva suas mudanças aqui -->

## Motivação

<!-- Por que essas mudanças são necessárias? -->

## Módulos Afetados

- [ ] Contracts
- [ ] Invoices
- [ ] People
- [ ] Communications
- [ ] Starter Kit
- [ ] Overview/Roadmap

🔗 Sincronização com Repositórios

Ao documentar funcionalidades:

1. Coordene com mantenedores dos repositórios de código (filament-core-contracts, etc.)
2. Verifique terminologia - nomes de eventos, DTOs e contratos devem estar sincronizados
3. Teste exemplos no repositório de código correspondente antes de documentar
4. Referencie issues do repositório de origem quando documentar novas features

🏗️ Estrutura da Documentação

docs/
├── overview/              # Roadmap técnico e visão geral
├── contracts/             # Documentação de contratos
├── invoices/              # Módulo de faturas
├── people/                # Módulo de pessoas
├── communications/        # Módulo de comunicações
├── starter-kit/           # Starter Kit Laravel
└── snippets/              # Diagramas e snippets reutilizáveis

🐛 Reportando Problemas

Ao encontrar problemas na documentação:

1. Verifique se já existe uma issue aberta
2. Crie uma nova issue com:
   • Título descritivo
   • Localização do problema (arquivo e linha)
   • Problema encontrado (link quebrado, informação incorreta, etc.)
   • Sugestão de correção se possível

💡 Sugestões e Melhorias

Sugestões são bem-vindas! Abra uma issue com:

• Descrição clara da melhoria
• Justificativa - por que isso beneficiaria o projeto
• Exemplos se aplicável

📚 Recursos

• Diretrizes para Agentes - Padrões técnicos e diretrizes
• Changelog - Histórico de mudanças do projeto
• Repositório GitHub - Código fonte
• Conventional Commits
• VitePress Documentation

❓ Dúvidas

Se tiver dúvidas:

1. Consulte Diretrizes para Agentes primeiro
2. Procure em issues fechadas
3. Abra uma nova issue com suas perguntas

---

Obrigado por contribuir com o Filament Core Suite! 🚀