Como escrever um documento de design (RFC) sobre o qual os revisores possam decidir

Objetivo

Deixar que uma mudança maior seja decidida pelas pessoas que terão de conviver com ela, com base num documento que se lê em vinte minutos e antes de alguém escrever o código. Mais tarde, o mesmo documento serve de registro do motivo pelo qual o sistema é como é.

Pré-requisitos

Uma mudança grande ou controversa demais para a descrição de um pull request; revisores conhecidos com autoridade para aprovar; um lugar junto ao código (um diretório docs/rfcs/, um arquivo numerado, um pull request). A PEP 1 e o modelo de RFC do Rust são exemplos públicos de processos assim. O capítulo de documentação de «Software Engineering at Google» afirma que os modelos usados lá exigem que se considerem segurança, internacionalização, necessidades de memória e privacidade, e que essas partes costumam ser revisadas por especialistas da respectiva área.

Passos

1. Descrever o problema antes de qualquer proposta: quem é afetado, o que acontece hoje, que restrição força uma mudança. Se o problema não couber num parágrafo, o documento ainda não está maduro.
2. Listar os objetivos como afirmações numeradas e verificáveis, e acrescentar não objetivos que delimitem o escopo. Os não objetivos evitam que a revisão se disperse em desejos vizinhos.
3. Explicar a proposta duas vezes, como prevê o modelo do Rust: uma no nível do usuário (como a mudança se apresenta a quem a usa) e outra no nível de referência, com semântica exata, formatos e casos-limite.
4. Registrar as alternativas consideradas e por que cada uma foi descartada. A PEP 1 prevê uma seção sobre ideias rejeitadas, com justificativa, para que a mesma ideia não volte a ser levantada; o modelo do Rust tem para isso «Rationale and alternatives».
5. Nomear com honestidade as desvantagens, as consequências para a compatibilidade, a migração e o rollout, e os custos operacionais; um documento sem desvantagens parece publicidade.
6. Terminar com as questões em aberto, separadas entre «precisa ser decidida nesta revisão» e «pode ser esclarecida durante a implementação».
7. Distribuir com um prazo para a leitura, responder aos comentários no próprio documento em vez de no chat e registrar o desfecho numa linha de status (rascunho, aceito, rejeitado, substituído). Manter os documentos rejeitados: eles respondem à próxima pessoa que tiver a mesma ideia.

Resultado esperado

Os revisores discutem o problema e as ponderações, não a falta de contexto; o documento aceito torna-se a referência para a implementação e, como sugere o capítulo da Google citado, no lançamento passa a ser a medida para avaliar se os objetivos definidos foram atingidos.

Limites e base de verificação

Um documento de design não é uma especificação; os detalhes mudam na implementação, e o documento deve dizer quais partes são vinculativas. Para mudanças pequenas, o ritual custa mais do que traz. A estrutura segue os modelos citados; aqui não foi medido nenhum efeito sobre a qualidade das decisões.