Quando você precisa de um RFC

Um ADR registra uma decisão que foi tomada. Um RFC é como uma decisão é tomada quando ela não cabe na cabeça de uma pessoa.

Este repositório tem uma pessoa humana contribuindo e 3.834 commits, então ele nunca precisou de um. Esse é o ponto de partida honesto, e é também por que as condições de gatilho valem ser conhecidas com precisão. Um processo de RFC adotado antes de ser necessário é pura cerimônia, e um adotado depois de ser necessário chega como reação a algo que já deu errado.

Os quatro gatilhos

Mais de uma resposta razoável. Se existe uma abordagem óbvia, escreva-a e abra o pull request. Um RFC é para uma bifurcação, não para uma estrada.

A decisão afeta trabalho que outras pessoas estão fazendo. Uma mudança num objeto de serviço que três times chamam não é sua para tomar sozinho, por mais certo que você esteja.

É cara de reverter. Uma mudança de esquema, uma interface pública, uma dependência. A tabela de reversibilidade do curso de ser dono se aplica direto: as três linhas de baixo merecem um RFC e as três de cima não.

Alguém já fez objeção. Um pull request com uma discordância nos comentários virou um RFC tendo alguém chamado assim ou não. E ele vai ser conduzido no pior lugar possível (um diff) a menos que alguém o mova.

Um gatilho basta. Dois tornam óbvio.

flowchart TB
  Q["uma mudança técnica"] --> A{"mais de uma resposta razoável?"}
  A -->|"não"| P["abra o pull request"]
  A -->|"sim"| B{"afeta o trabalho de outras pessoas, cara de reverter, ou já teve objeção?"}
  B -->|"não"| P
  B -->|"sim"| R["escreva um RFC"]

O assunto deste curso

Uma pergunta real e arguível neste repositório, que a aula 3 transforma num RFC.

O app/queries/admin/stats_query.rb é o maior arquivo da aplicação com 390 linhas, e um dos mais mudados com doze commits. Ele contém vinte e três métodos e devolve um objeto Data com vinte e três campos.

Oito desses campos terminam em _chart_json, e isto é o que produz um deles:

def self.format_engagement_chart(trends)
  {
    labels: trends.map { |t| t[:label] },
    datasets: [
      { label: I18n.t("admin.dashboard.stats.enrollments"),
        data: trends.map { |t| t[:enrollments] },
        borderColor: "#007AFF",
        backgroundColor: "rgba(0, 122, 255, 0.05)",
        fill: true, tension: 0.4, pointRadius: 0,
        pointHoverRadius: 6, borderWidth: 2.5 },
      # ...and the same again for completions, in "#CC0000"
    ]
  }.to_json
end

Cores em hexadecimal, borderWidth, pointHoverRadius, tension. E o MEMORY.md declara:

"Consultas precisam devolver objetos Data puros ou Arrays de Models do ActiveRecord. São operações puramente de Domínio e nunca devem conter lógica de apresentação, formatação de HTML, ou roteamento de URL."

Por que este é um bom assunto de RFC e não um relatório de bug

Porque o código tem uma razão real para ser assim, e ler isso é o que faz disto um RFC e não uma correção.

Rails.cache.fetch("admin/stats/#{resolved}", expires_in: 5.minutes) do

A computação inteira, incluindo o JSON dos gráficos, está dentro de um cache de cinco minutos. Mover a formatação para um helper significaria as cores e a serialização rodarem em toda requisição do painel em vez de uma vez a cada cinco minutos.

Esse é um argumento genuíno, não uma racionalização. Alguém pesou uma regra documentada contra um benefício de cache e escolheu o benefício de cache. E um RFC que finge o contrário será rejeitado por quem o escreveu: corretamente.

Os quatro gatilhos estão presentes: existem pelo menos três respostas razoáveis, o arquivo está numa superfície de admin compartilhada, um Result público de 23 campos é caro de mudar. E uma regra documentada já está em tensão com ele.

O que um RFC não é

Não é um ADR. Um RFC é uma proposta, editada durante a revisão, com uma decisão no fim. Um ADR é imutável e registra o desfecho. A aula 6 é sobre como um vira o outro.

Não é um documento de design. Um RFC defende uma direção e nomeia o que ela custa. Um documento de design especifica como algo funciona, e vem depois: ou nunca, para uma mudança deste tamanho.

Não é um jeito de conseguir permissão. Se a resposta é óbvia e você quer respaldo, um RFC é um jeito lento de obter o que um pull request teria dado em uma hora.

Não é um lugar para pensar. Traga uma posição. Um RFC que abre com "o que devemos fazer com o StatsQuery?" produz uma discussão em vez de uma decisão. E a aula 5 é sobre por quê.

Pontos-chave

• Um ADR registra uma decisão; um RFC é como uma se toma quando não cabe numa cabeça.
• Quatro gatilhos: mais de uma resposta razoável, afeta outras pessoas, é cara de reverter, alguém fez objeção.
• O assunto aqui: uma consulta de 390 linhas devolvendo oito campos _chart_json, contra uma regra que proíbe apresentação em consultas.
• É um RFC e não um relatório de bug porque o código tem razão real: a computação inteira está num cache de cinco minutos.
• Um RFC não é um ADR, não é documento de design, não é autorização, e não é lugar para começar a pensar.