Qualidade de Código

Repositorios open source não crescem apenas com código bom. Eles crescem quando a colaboração é previsível, a branch principal permanece protegida e novos contribuidores conseguem entender rapidamente como participar sem pedir instruções por telepatia. Este guia reúne um modelo operacional prático para organizar branches, pull requests, revisão, automação de qualidade e documentação básica em projetos no GitHub.

Este guia operacional reúne um fluxo prático para manter um repositório open source colaborativo, previsível e atraente para contribuidores. A base recomendada combina branches curtas, pull requests pequenas, revisão obrigatória, automação de qualidade e documentação de entrada clara para reduzir atrito e aumentar a confiança no projeto.

Objetivos do repositório

Um repositório open source bem operado deve atender quatro objetivos ao mesmo tempo: facilitar colaboração, proteger a branch principal, manter qualidade contínua e tornar simples a descoberta e adoção do projeto. Repositórios com README claro, instruções de contribuição e revisões bem estruturadas dão mais contexto para novos usuários e melhoram a experiência de quem quer abrir issue, testar ou enviar PR.

Modelo operacional recomendado

O modelo abaixo funciona bem para projetos individuais que querem crescer com colaboração externa.

Regras de branch

A branch main deve representar sempre o estado mais confiável do projeto. Para isso, a proteção da branch deve impedir merge sem checks obrigatórios, sem revisão e sem resolução das conversas abertas quando essas regras forem adotadas no repositório.

Política sugerida

• Bloquear push direto em main.
• Exigir pull request para merge.
• Exigir pelo menos 1 review aprovado; usar 2 para código sensível, segurança ou infraestrutura.
• Exigir status checks obrigatórios, como testes, lint e build.
• Exigir que conversas do PR sejam resolvidas antes do merge.
• Exigir branch atualizada com a base antes de merge quando o projeto tiver bastante atividade.
• Ativar CODEOWNERS para solicitar revisão automática por área do código.

Convenção de nomes de branches

feat/nome-curto-da-feature
fix/descricao-curta-do-bug
docs/ajuste-readme-ou-guia
refactor/modulo-ou-componente
chore/tarefa-operacional

Regras práticas para branches

• Cada branch deve tratar um único objetivo funcional.
• Branches devem durar pouco tempo para reduzir conflitos.
• Evitar PRs gigantes; o ideal é manter diffs pequenos e revisáveis.

Fluxo de contribuição

O fluxo ideal para colaboradores é simples: criar branch, implementar mudança pequena, validar localmente, abrir PR com contexto claro e responder ao review até o merge. O GitHub destaca que bons PRs melhoram a colaboração quando deixam explícitos o objetivo da mudança, o tipo de feedback esperado e a sequência sugerida para revisão.

Fluxo padrão

1. Abrir uma issue, quando a mudança exigir discussão ou alinhamento prévio.
2. Criar branch a partir de main.
3. Implementar a mudança em commits pequenos e objetivos.
4. Rodar testes, lint e validações locais.
5. Atualizar documentação e changelog, quando aplicável.
6. Abrir PR usando o template oficial.
7. Corrigir feedback, reexecutar checks e concluir merge após aprovação.

Padrão para commits

Commits curtos e legíveis facilitam revisão, rastreabilidade e automação futura. Mesmo quando o projeto não usa Conventional Commits de forma rígida, uma convenção consistente ajuda a entender o histórico e gerar releases com menos esforço.

Convenção sugerida

feat: adiciona cache para respostas da API
fix: corrige validação de token expirado
docs: melhora instruções de instalação
refactor: simplifica carregamento de configurações
test: cobre cenário de retry no cliente HTTP
chore: atualiza workflow de CI

Regras para commits

• Um commit deve representar uma ideia principal.
• Evitar commits genéricos como update, fixes ou changes.
• Preferir verbo no presente e descrição objetiva.

Template de README

O README é o principal ponto de entrada do repositório e deve explicar por que o projeto existe, como instalar, como usar e como contribuir. Um README forte reduz dúvidas repetitivas e aumenta a chance de adoção, fork e estrelas quando o valor do projeto fica visível rapidamente.

Copie e adapte o modelo abaixo para README.md.

# Nome do Projeto

Descrição curta em 1 ou 2 frases explicando o problema que o projeto resolve e para quem ele serve.

## Status

- Estado: ativo / beta / experimental / maintenance
- Versão atual: x.y.z
- Licença: MIT / Apache-2.0 / outra

## Por que este projeto existe

Explique a dor resolvida, o diferencial e o contexto de uso.

## Principais recursos

- Recurso 1
- Recurso 2
- Recurso 3

## Demonstração

Inclua screenshot, GIF, terminal output ou link para demo.

## Instalação

```bash
# exemplo
make install
```

## Uso rápido

```bash
# exemplo
comando --help
```

## Exemplo

Mostre o menor exemplo útil possível.

## Arquitetura

Explique os componentes principais em poucas linhas.

## Requisitos

- Linguagem / runtime
- Dependências externas
- Versão mínima suportada

## Desenvolvimento local

```bash
# setup
make setup

# testes
make test

# lint
make lint
```

## Roadmap

- [ ] Item 1
- [ ] Item 2
- [ ] Item 3

## Como contribuir

Leia [CONTRIBUTING.md](./CONTRIBUTING.md) antes de abrir issue ou pull request.

## Segurança

Informe como reportar vulnerabilidades de forma responsável.

## Licença

Este projeto está licenciado sob a licença X. Consulte `LICENSE`.

Template de CONTRIBUTING

Um CONTRIBUTING.md claro reduz retrabalho e torna previsível a entrada de novos colaboradores. Também ajuda a filtrar contribuições de baixa qualidade ao definir escopo, processo e padrão técnico antes do primeiro PR.

Copie e adapte o modelo abaixo para CONTRIBUTING.md.

# Contribuindo

Obrigado pelo interesse em contribuir.

## Antes de começar

- Leia o README.
- Verifique se já existe issue ou PR relacionado.
- Para mudanças grandes, abra uma issue antes de implementar.

## Tipos de contribuição

- Correção de bugs
- Novos recursos
- Melhorias de documentação
- Testes
- Refatorações
- Exemplos e templates

## Fluxo de trabalho

1. Faça fork do repositório, se necessário.
2. Crie uma branch a partir de `main`.
3. Implemente uma mudança pequena e focada.
4. Adicione ou atualize testes.
5. Rode lint, testes e validações locais.
6. Atualize documentação relevante.
7. Abra um pull request usando o template.

## Padrão de branches

- `feat/*`
- `fix/*`
- `docs/*`
- `refactor/*`
- `chore/*`

## Padrão de commits

Use mensagens claras. Exemplo:

```text
feat: adiciona suporte a configuração por arquivo
fix: corrige falha ao processar credenciais vazias
```

## Qualidade mínima

Um PR deve:

- Passar em todos os checks de CI.
- Manter ou melhorar cobertura de testes quando aplicável.
- Incluir documentação para mudanças visíveis ao usuário.
- Não misturar refatoração ampla com feature nova sem necessidade.

## Pull requests

Ao abrir um PR:

- Explique o problema resolvido.
- Descreva a solução adotada.
- Liste impactos, trade-offs e limitações.
- Vincule a issue correspondente, quando houver.
- Adicione evidências, screenshots ou logs quando fizer sentido.

## Código de conduta

Ao participar deste projeto, espera-se comunicação respeitosa e colaboração construtiva.

## Dúvidas

Use issues, discussões ou o canal definido no README.

Template de pull request

Um template de PR reduz ambiguidades e melhora a qualidade da revisão porque padroniza contexto, validação e impacto da mudança. Também ajuda o mantenedor a identificar rapidamente se o PR está pronto para revisão ou ainda precisa de ajustes.

Copie e adapte o modelo abaixo para .github/pull_request_template.md.

## Resumo

Descreva a mudança em 2 a 5 linhas.

## Problema resolvido

Explique qual problema este PR resolve e por que a mudança é necessária.

## Tipo de mudança

- [ ] Bug fix
- [ ] Nova feature
- [ ] Refatoração
- [ ] Documentação
- [ ] Testes
- [ ] Chore / manutenção

## Como validar

Descreva o passo a passo para testar.

## Evidências

Inclua screenshots, logs, GIFs ou exemplos de saída quando aplicável.

## Checklist

- [ ] Li as diretrizes de contribuição.
- [ ] Mantive o escopo do PR pequeno e objetivo.
- [ ] Rodei testes e validações locais.
- [ ] Atualizei documentação relevante.
- [ ] Adicionei ou ajustei testes quando necessário.
- [ ] O PR está pronto para revisão.

## Issues relacionadas

Closes #

Checklist de revisão para mantenedores

Um checklist explícito ajuda a padronizar reviews e melhora a consistência da qualidade entre mantenedores. O GitHub trata o review de PR como mecanismo central para aprovar, comentar e pedir mudanças antes do merge.

Checklist sugerido

• O objetivo do PR está claro?
• O escopo está pequeno o suficiente para revisão segura?
• A solução está correta tecnicamente?
• Existem testes cobrindo o comportamento alterado?
• Há impacto em segurança, performance, compatibilidade ou DX?
• A documentação foi atualizada?
• Os checks obrigatórios passaram?
• Há necessidade de envolver CODEOWNERS ou especialista do domínio?

Regras de branch no GitHub

A configuração abaixo é uma boa base operacional para a branch main.

Configuração sugerida

• Require a pull request before merging: habilitado
• Require approvals: 1 mínimo; 2 para áreas críticas
• Dismiss stale approvals when new commits are pushed: habilitado
• Require review from Code Owners: habilitado quando houver CODEOWNERS
• Require status checks to pass before merging: habilitado
• Require conversation resolution before merging: habilitado
• Block force pushes: habilitado
• Block deletions: habilitado

Estrutura mínima recomendada do repositório

Uma estrutura previsível melhora a descoberta do projeto e reduz o tempo até a primeira contribuição.

.
├── .github/
│   ├── ISSUE_TEMPLATE/
│   ├── workflows/
│   └── pull_request_template.md
├── docs/
├── src/
├── tests/
├── README.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── LICENSE
└── SECURITY.md

Automação mínima recomendada

A automação deve verificar qualidade em todo PR e proteger a branch principal contra regressões. O GitHub Actions oferece CI/CD integrado e o GitHub Code Quality pode reportar problemas de qualidade em PRs e scans do repositório.

Pipeline mínimo

• Build
• Testes unitários
• Lint
• Formatação
• Análise estática
• Security/dependency scan

Exemplo de política operacional

• Nenhum PR entra em main sem checks verdes.
• Nenhuma feature entra sem documentação mínima.
• Bugs críticos exigem teste de regressão.
• Refatorações grandes devem ser quebradas em etapas menores.

Diretrizes para ganhar adoção e estrelas

Projetos ganham mais atenção quando o valor fica evidente nos primeiros segundos de leitura do README e quando existe prova de utilidade, como demo, exemplos e instalação simples. Para um projeto open source crescer, a operação do repositório deve tratar onboarding e reputação como parte do produto, não como detalhe administrativo.

Práticas com maior impacto

• Mostrar proposta de valor logo no topo do README.
• Incluir GIF, screenshot ou exemplo executável.
• Manter instruções de instalação curtas e confiáveis.
• Aceitar contribuições com regras claras e previsíveis.
• Responder issues e PRs com consistência para passar confiança à comunidade.

Kit inicial de arquivos

Para colocar este guia em prática rapidamente, o repositório deve começar com os seguintes arquivos:

• README.md
• CONTRIBUTING.md
• .github/pull_request_template.md
• .github/ISSUE_TEMPLATE/bug_report.yml ou .md
• .github/ISSUE_TEMPLATE/feature_request.yml ou .md
• .github/CODEOWNERS
• LICENSE
• SECURITY.md
• CODE_OF_CONDUCT.md
• Workflow de CI em .github/workflows/ci.yml

Política operacional resumida

A política central do repositório pode ser registrada desta forma:

Todo código entra por pull request pequeno, com contexto claro, revisão obrigatória, automação de qualidade e documentação atualizada. A branch principal permanece protegida e sempre pronta para uso.