Como contribuir

Todo o conteúdo é Markdown num repositório aberto. Não existe CMS, não existe conta: contribuição é pull request.

O jeito rápido: corrigir algo pequeno

Achou uma flag errada, um link quebrado, um erro de digitação?

1. Role até o fim da página e clique em Editar esta página.
2. O GitHub abre o arquivo no editor, já num fork seu.
3. Corrija, escreva uma descrição de uma linha e abra o pull request.

Não precisa clonar nada. Correção pequena costuma ser aceita no mesmo dia.

O jeito completo: escrever uma página

1. Rodar o portal localmente

git clone https://github.com/devopsbr/portal.git && cd portal && npm install && npm run dev

O site sobe em http://localhost:4321 com recarga automática. Alterou o Markdown, o navegador atualiza.

2. Escolher o tipo antes de escrever

Esta é a decisão mais importante e a que mais gente erra. Antes da primeira linha, responda: o leitor desta página quer aprender, resolver, consultar ou entender?

A resposta determina em qual diretório o arquivo vai e como ele é escrito. O padrão editorial detalha cada tipo — leia antes de escrever, não depois.

src/content/docs/
├─ trilhas/<dominio>/<pagina>.md      aprender, guiado, na ordem
├─ guias/<dominio>/<pagina>.md        resolver um problema agora
├─ referencia/<pagina>.md             consultar rápido
└─ conceitos/<grupo>/<pagina>.md      entender o porquê

3. Preencher um rascunho existente

A maior parte do portal já tem o índice pronto e o texto pendente. Essas páginas trazem rascunho: true no frontmatter e um aviso âmbar no topo.

Esse é o melhor lugar para começar. O roteiro de seções já está definido e revisado — você escreve o conteúdo seguindo aquele plano e troca rascunho: true por rascunho: false.

Se durante a escrita ficar claro que o roteiro está errado, mude o roteiro e explique o porquê na descrição do pull request. O plano não é sagrado, só é o ponto de partida.

4. Verificar antes de enviar

npm run build

O build valida todo o frontmatter contra o schema e reprova link interno quebrado. Se passar aqui, passa no CI.

npm run taxonomia

Confere dominio e tags. São esses campos que ligam a sua página às outras no bloco Relacionados do rodapé — sem tag compartilhada, a página nasce sem nenhum link de entrada e só é encontrada por quem já sabe que ela existe. Use tags que já existam em outras páginas; a verificação reprova tag usada uma vez só.

npm run preview

A busca só é indexada no build, então é aqui — e não no dev — que você confere se a sua página aparece na pesquisa.

5. Abrir o pull request

Descreva o que muda para o leitor, não o que muda no arquivo. “Explica por que liveness não deve checar o banco” é útil; “atualiza kubernetes.md” não é.

O que é bem-vindo

• Corrigir informação desatualizada — infraestrutura envelhece rápido, e isso é o tipo de contribuição mais valiosa que existe aqui.
• Preencher rascunho seguindo o roteiro.
• Acrescentar a armadilha que te custou uma madrugada.
• Ferramenta nova no catálogo — com o campo de quando não usar preenchido de forma honesta.
• Template comentado que você usa em produção.

O que não é

• Conteúdo promocional de produto, mesmo disfarçado de tutorial.
• Tradução automática de documentação em inglês.
• Página que mistura dois propósitos.
• Recomendação sem menção a custo ou limitação.
• “Lista das 10 melhores ferramentas de X” sem critério explícito.

Dúvida sobre escopo?

Abra uma issue antes de escrever. É melhor discutir o índice em cinco linhas do que descobrir depois de duas mil palavras que a página deveria ser duas.

Licença

Conteúdo sob CC BY-SA 4.0, código sob MIT. Ao contribuir, você concorda em publicar sob esses termos — e continua sendo creditado no histórico do Git.