| Data | Referências | Colaborações |
|---|---|---|
| 10 de janeiro, 2022 | @pessoa_1 @pessoa_2 | @pessoa_3 @pessoa_4 |
Sumário: Resumo curto de uma ou duas sentenças sobre a proposta.
A RFC começa com um breve resumo. Esse seção deve ter um ou dois parágrafos que apenas explicam qual vai ser o objetivo da RFC, mas sem entrar em muitos detalhes do "porque", "porque não", "como", etc. Qualquer pessoa que abrir esse documento deve ter uma entendimento claro de qual que é a itenção da RFC só de ler esse(s) parágrafos.
A próxima seção é a seção de "Histórico". Esse seção deve ter pelo menos dois parágrafos e pode se extender a até uma página inteira em alguns casos. O objetivo da seção de histórico é: como um pessoa nova ao projeto eu consigo ler a seção de histórico e qualquer link presente e ter todo o contexto do porquê esse mudança é necessária?
Se você não consegue mostrar para uma pessoa aleatória a seção de histórico e fazer com que ela obtenha quase todo o contexto do porquê essa RFC é necessária, então a seção de histórico não está suficientemente completa. Para ajudar, coloque links para outras RFCs, discussões e outros conteúdos necessários para providenciar contexto sem que você tenha que simplemente repetir.
A próxima seção necessária é a "Proposta" ou "Objetivo". Dado o histórico acima, essa seção propõe a solução. Essa parte deve ser uma visão geral do "como será feito" da solução, mas para mais detalhes outras seções serão utilizadas.
A medida que a RFC evolui, é comum que ideias sejam abandonadas. Ao invés de simplemente apagar elas do documento, você deveria tentar organiza-las em sub-seções para deixar claro que elas foram abandonadas e, ao mesmo tempo, explicar porquê elas foram abandonadas.
Ao compartilhar a RFC ou quando alguém for ler a RFC no futuro, é comum seguir o mesmo caminho e cair nas mesmas armadilhas que foram aprendidas no processo. Ideias abandonadas são uma forma de reconhecer esses caminhos e explicar as armadilhas e o porquê da ideia ter sido adandonada.
Desse ponto em diante, as seções e cabeçalhos não possuem um formato específico
e ficam a critério das pessoas que estão escrevendo a RFC. Seções são marcadas
com nível 2 de cabeçalho (## Cabeçalho 2). Tente organizar suas informações
em seções auto-sufcientes que respodam alguma pergunta importante, e ordene as
suas seções de forma que o conhecimento necessário seja acumulado (ao invés de
forçar a pessoa que esteja lendo a pular entre seções para adquirir contexto).
Seções geralmente são geralmente divididas em sub-seções estilizadas com
### Cabeçalho 3. Essas sub-seções ajudam a organizar ainda mais as
informações para auxiliar a leitura e discussão.
Muitas RFCs tem uma seção de "implementação" que detalha como implementação será feita. Esse seção deve explicar uma visão de mudanças de API (internas ou externas), mudanças em pacotes, etc. O objetivo é dar uma ideia para as pessoas que estão revisando de quais sub-sistemas precisam ser alterados e área de impacto dessas mudanças.
Esse conhecimento pode gerar recomendações de formas alternativas de implementação que talvez sejam mais idiomáticas ao projeto or que resulte em menos mudanças. Or então pode resultar no entendimento de que a solução proposta nessa RFC é muito complexa para o problema que está tentando ser resolvido.
Para as pessoas que estão criando a RFC, detalhar e escrever a implementação em um nível mais alto pode server como uma forma de "debug com pato de borracha" e pode identificar muitos problemas comuns ou até problemas que nem sabemos que não sabemos antes mesmo de escrever qualquer linha de código.
Se essa RFC possue mudanças que irão impactar usuários(as), é importante ter uma seção de "UI/UX". Mudanças que impactam usuários(as) incluem mudanças de API expostas externamente, mudanças no formato de arquivos de configuração, mudanças de saída na linha de comando, etc.
Essa seção é efetivamente a seção de "implementação" para a experiência do(a) usuário(a). O objetivo é explicar as mudanças necessárias, qualquer impacto em relação a compatibilidade com versões anteriores, qualquer impacto no fluxo de trabalho, etc.
Como a pessoa que está revisando a RFC, essa seção deve ser analisada para
verificar se as mudanças propostas se encaixam na experiência estabelecida pelo
projeto. Por exemplo, se a mudança de UX está propondo um argumento -foo_bar
mas todos os outros argumentos usam hífens, como -foo-bar, então essa é uma
mudança que merece ser discutida em um comentário. Além do mais, se as quebras
de compatibilidade não são toleráveis or existe uma forma de fazer a mudança
preservando a compatibilidade, essas opções devem ser exploradas.
Todas as RFCs devem seguir um estilo e estrutura similar para facilitar a leitura.
As RFCs são escritas em formato Markdown seguindo a sintaxe do GitHub. Cada linha no arquivo deve ter menos de 80 caracteres para facilitar a leitura em modo texto e comentários durante a revisão da PR.
## Cabeçalho 2 dever ser utilizado para títulos de seções. Não use
# Cabeçalho 1.
### Cabeçalho 3 deve ser usado para sub-seções.
Os próximos estilos de cabeçalho podem ser utilizados para seções mais
aprofundadas, mas é raro quem uma RFC vá além do #### Cabeçalho 4, ou que até
chegue no #### Cabeçalho 4.
Ao criar listas, é comum que a primeira frase/sentença/paralavra esteja em negrito para dar atenção à algum ponto ou categoria. Por exemplo, uma lista de considerações para uma API:
- Formato deve ser widget
- Protocolo deve ser widget-rpc
- Compatibilidade com outras versões deve ser considerada
Blocos de código devem usar três crases seguidas e realce de sintaxe quando necessário. Por exemplo:
```hcl
module "meu_modulo" {
# ...
}
```
Irá gerar o bloco:
module "meu_modulo" {
# ...
}Durante a criação da RFC é comum que sejam usadas imagens e outros artefatos para facilitar a descrição de certas partes da proposta. Esses arquivos podem ser colocados em sub-pastas dentro da pasta raíz da RFC.
A imagem então pode ser referenciada no arquivo Markdown usado um texto alternativo e o caminho relativo para o arquivo:
Se uma imagem for gerada a partir de um arquivo fonte (como um arquivo .psd
do Photoshop), esses também deverão ser colocados no repositório afim de
possibilitar o acesso público à fonte e possíveis alterações ou derivações do
trabalho original. Esses arquivos devem fircar em uma sub-pasta chamada src
dentro da pasta da RFC.
rfcs
└── RFC-001
├── img
│ └── infra-azure.png
├── RFC-001.md
└── src
└── azure.drawio