Guias de projetos

Modelo de README do GitHub para um projeto de código aberto

Um README útil no GitHub responde rapidamente a quatro perguntas: o que este projeto faz, para quem ele serve, como experimentá-lo e onde conseguir ajuda? Use o modelo Markdown abaixo como ponto de partida e substitua cada marcador por informações verificadas no seu projeto.

Equipe editorial do GitHubStart · Atualizado

Copie este modelo de README em Markdown

Este é um modelo inicial redigido, não um exemplo de software funcional. Substitua o texto entre colchetes, confira se os arquivos mencionados existem e remova seções que não se aplicam. As linhas de instalação e execução abaixo são comentários para impedir a execução acidental de comandos de preenchimento.

# [Nome do projeto]

[Uma frase: o problema, o usuário pretendido e o resultado.]

## Exemplo
[Mostre uma pequena entrada e a saída esperada ou adicione uma captura de tela.]

## Início rápido
Requisitos: [ambiente de execução/versão e serviços necessários].

```sh
# Substitua pelo seu comando de instalação verificado.
# Substitua pelo menor comando que produza um resultado útil.
```

Resultado esperado: [o que o leitor deve ver].

## Configuração
[Configurações necessárias, valores de exemplo seguros e onde armazenar segredos.]

## Quando usar
- [Um caso de uso concreto]
- [Um segundo caso de uso]

## Limitações
[Entradas não suportadas, maturidade e restrições de desempenho ou plataforma.]

## Documentação e ajuda
[Inclua um link para a documentação e explique onde fazer perguntas.]

## Como contribuir
Consulte [CONTRIBUTING.md](CONTRIBUTING.md).
Relate um problema reproduzível na aba Issues do repositório.

## Licença
Consulte [LICENSE](LICENSE).

Adapte o exemplo ao tipo de repositório

Para uma ferramenta de linha de comando, mostre um arquivo de entrada, o comando e uma saída curta. Para uma biblioteca, mostre o menor exemplo completo de importação e chamada, incluindo o valor de retorno esperado. Para uma aplicação web, mostre o fluxo principal e explique se existe uma demonstração hospedada ou uma instalação local.

Evite usar uma captura de tela como única explicação de uma API: os leitores devem conseguir copiar o código. Por outro lado, uma aplicação visual pode se beneficiar de uma captura com uma descrição clara do que o usuário está fazendo. Use exemplos reais da versão que você distribui atualmente.

  • Biblioteca: instalação, ambiente de execução suportado e uma chamada completa de função.
  • CLI: entrada, comando, saída e como os erros são informados.
  • Aplicação web: link para demonstração ou instalação local, configuração e captura da tarefa principal.
  • Conjunto de dados: origem, formato, licença e um pequeno registro de exemplo.

Confira o README antes de compartilhá-lo

Experimente o início rápido em um ambiente limpo, em vez de uma máquina já configurada para desenvolvimento. Verifique se é necessário algum pacote global não declarado, registro privado ou arquivo local. Se a configuração exigir uma conta ou serviço pago, informe isso antes do primeiro comando.

Abra os links de documentação e imagens pela página do repositório. Confirme que os nomes dos arquivos de contribuição e licença correspondem aos do repositório e remova links quebrados. Um README curto e preciso é melhor que um modelo impressionante cheio de promessas que você não implementou.

  • Remova marcadores e afirmações sem respaldo.
  • Não inclua tokens reais, senhas nem URLs privadas nos exemplos.
  • Verifique se a saída esperada corresponde à versão publicada.
  • Diga aos leitores o que incluir ao relatar um problema.

Use o README como resumo de lançamento

Depois de completar o modelo, extraia uma apresentação curta: uma frase sobre o problema, um exemplo do resultado e um link para experimentar. Isso se torna o ponto de partida de uma publicação na comunidade. Mantenha o README original como fonte detalhada e adapte cada apresentação ao leitor, em vez de repetir um parágrafo promocional em todo lugar.

Perguntas frequentes

Este é um README de repositório ou de perfil?

Este modelo é para um repositório de software. Um README de perfil apresenta uma pessoa e precisa de outras seções, como seu trabalho e suas preferências de contato.

Devo adicionar selos de estrelas no início?

Somente se ajudarem o leitor. Mantenha a finalidade e o início rápido em destaque. Um selo não substitui a explicação do que o projeto faz.

Posso usar este modelo em um projeto privado?

Sim. Substitua os links de suporte público pelos canais reais de ajuda da sua equipe, explique os requisitos de acesso e não inclua credenciais no documento.

Referências