Temas de discussão

Analisamos 604 comentários não-bot em 60 PRs de alto atrito, classificando-os em 9 temas usando codificação baseada em palavras-chave. Cada tema abaixo inclui sua frequência entre os PRs analisados, uma descrição do que ele captura e citações de evidência de discussões reais de revisão.

Visão geral da frequência dos temas

Tema	PRs com o tema	Participação nos PRs analisados
Design de API e valores padrão	23	38,3%
Evidência de testes e cobertura	23	38,3%
Padrões de componentes e estilização	21	35,0%
Gerenciamento de estado e fluxo de dados	21	35,0%
Documentação de código	19	31,7%
Segurança de tipos e tratamento de erros	18	30,0%
Follow-up e scope creep	15	25,0%
Segurança e permissões	12	20,0%
Nomenclatura e consistência	7	11,7%

Os dois principais temas — design de API e evidência de testes — aparecem cada um em mais de um terço dos PRs de alto atrito. Todo tema aparece em pelo menos 7 PRs, confirmando que são padrões sistemáticos e não discussões pontuais.

---

1. Design de API e valores padrão (38,3%)

Debates sobre o design da superfície de API, valores padrão, nulabilidade, regras de validação e semântica de contrato.

Evidência

“Not sure if this is the right move. Should we force overwrite if auto_open_prs and stopping point is not open_pr, or ignore an incorrect stopping point, or reject at validation time? Imo, I don’t like the idea of conflicting options.” — #111697, comentário de revisão

“Should we start this as False, then flip it on in prod? Might be slightly easier to ensure it’s off by default.” — #111723, comentário de revisão

“I think we want to minimize the queries and lookups we do in these data objects since the end goal is for them to be fully self-contained serializable objects with all the primitives required to render.” — #111674, comentário de revisão

Padrão

Os revisores frequentemente debatem qual é o valor padrão “certo”, se as opções devem ser nuláveis e como lidar com configurações conflitantes. Sem um contrato explícito de como os defaults se propagam (nível de organização → nível de projeto → runtime), cada PR que introduz uma nova configuração reabre o mesmo debate de design.

---

2. Evidência de testes e cobertura (38,3%)

Solicitações de evidência de testes, discussão de lacunas de cobertura de testes e debates sobre metodologia de testes.

Evidência

“There should probably be a test in here which mounts, renders, then confirms that the PageContextProvider is actually providing the page context for sending to the AI. I’d also add a test with a nested case so we can test that DummyChart in DummyWidget in DummyDashboard nests.” — #111554, comentário de revisão

“Seems like quite a few paths simply do raise NotFound(...) and you’re simply matching on the hard coded string here which seems rather fragile. Thoughts on updating the sources to raise a more specific error maybe IntegrationNotFound that can be caught instead of comparing strings?” — #111691, comentário de revisão

“Maybe worth adding a test for when the circuit breaker allows the request, but the HTTP request itself returns a failed status code? So circuit breaker records success but the usual request error handling kicks in?” — #111723, comentário de revisão

Padrão

Os revisores pedem cenários de teste específicos que o autor não antecipou — casos de componentes aninhados, teste de caminhos de erro, casos extremos para circuit breakers. A discussão não é sobre se deve testar, mas sobre o que testar. Sem expectativas explícitas de teste por tipo de mudança, cada revisor aplica seu próprio julgamento sobre a evidência mínima de teste.

---

3. Padrões de componentes e estilização (35,0%)

Uso de componentes de frontend, abordagens de estilização e conformidade com o design system.

Evidência

“Can we avoid this inline style w/ prop of some kind?” — #111529, comentário de revisão (repetido 6 vezes neste PR)

“Neat that we have a loading indicator prop now! I was checking it out on scraps, but it seems like the button is still clickable. Does the callback get invoked still or is that handled with this state?” — #111490, comentário de revisão

“I don’t think we need the third prop here per previous conversations. I’d mostly use the register function just to wrap + name and make the third prop optional.” — #111554, comentário de revisão

Padrão

O padrão dominante são pedidos repetidos para evitar estilos inline em favor de props de componentes. Em #111529, o mesmo revisor deixou “can we avoid this inline style w/ prop of some kind?” seis vezes separadas em linhas diferentes. Esse é exatamente o tipo de atrito que um ADR ou regra de lint poderia eliminar. As discussões também focam em se componentes do design system devem ser usados em vez de implementações customizadas.

---

4. Gerenciamento de estado e fluxo de dados (35,0%)

Padrões de gerenciamento de estado, fluxo de dados entre componentes e serviços, segurança de migração.

Evidência

“I think keeping the org-level and project-level as 1:1 as possible will be a benefit, even if it doesn’t make sense. At the org-level validation will be hard, or at least annoying to resolve, as people typically push values up one field at a time.” — #111697, comentário de revisão

“Why do we bind here if the pipeline already has an organization slug on it?” — #111728, comentário de revisão

“Reading the comment on L116-118, it makes me wonder if we actually need state reactivity, or could we write directly to a ref?” — #111554, comentário de revisão

Padrão

Os revisores sondam o modelo de fluxo de dados: por que o estado é vinculado em certos pontos, se a reatividade é necessária e como a configuração se propaga entre escopos. Essas discussões frequentemente revelam premissas arquiteturais que não estão documentadas — o revisor precisa inferir o fluxo de dados pretendido apenas a partir do código.

---

5. Documentação de código (31,7%)

Solicitações de explicações, documentação de comportamento e esclarecimento de intenção.

Evidência

“Under what conditions would there not be an installation id? … Does this mean the GitHub org already has a Sentry installation? Does this mean we’re in a multi-org setup flow?” — #111728, comentário de revisão

“Should we be adding another mobx use case? Could we use react-query or react context instead, or is this because of also using the legacy form component?” — #111490, comentário de revisão

“When is it equal to -1? What’s the significance?” — #111728, comentário de revisão

Padrão

Os revisores fazem perguntas de “por quê” e “sob quais condições” que indicam comentários de código ou documentação ausentes. O revisor precisa pedir ao autor que explique um comportamento que poderia ter sido capturado em um comentário ou docstring.

---

6. Segurança de tipos e tratamento de erros (30,0%)

Correção de tipos, valores opcionais, padrões de tratamento de erros e segurança de exceções.

Evidência

“Do we need the cast for ReactNode? Seeing this multiple times in this file.” — #111529, comentário de revisão

“Same Q. Why is this optionally expected? Does this mean the GitHub org already has a Sentry installation? Does this mean we’re in a multi-org setup flow?” — #111728, comentário de revisão

“Seems like quite a few paths simply do raise NotFound(...) and you’re simply matching on the hard coded string here which seems rather fragile. Thoughts on updating the sources to raise a more specific error?” — #111691, comentário de revisão

Padrão

As discussões de segurança de tipos giram em torno de dois subtemas: (a) se os valores devem ser opcionais/nuláveis e as implicações dessa escolha, e (b) padrões de tratamento de erros (correspondência de strings vs. exceções tipadas). Ambos se beneficiariam de convenções explícitas documentadas em ADRs.

---

7. Follow-up e scope creep (25,0%)

Discussões sobre adiar trabalho, limites de escopo e rastreamento de follow-ups.

Evidência

“We’ll have to figure out why there are two names for things in different APIs and consolidate. As a follow up.” — #111697, comentário de revisão

“Yeah you’re right this seems wrong. I can follow up VDY-53.” — #111728, comentário de revisão

“Great work! I did a visual check and didn’t notice anything off. Ok except for the widget creation in a dashboard, but that is also in production and we can address in a follow up.” — #111775, comentário de revisão

Padrão

Um quarto dos PRs de alto atrito envolve negociar o que está no escopo vs. o que deve ser adiado. Os revisores identificam problemas, mas aceitam “follow up” como resolução — criando um rastreamento implícito de dívida técnica distribuído pelos comentários do PR em vez de um sistema centralizado.

---

8. Segurança e permissões (20,0%)

Implicações de segurança, modelos de permissão, fluxos de autenticação e discussões sobre superfície de ataque.

Evidência

“Should we put some permissions checks around this? Only admins will be able to edit integrations… I think we should hide or disable this button for regular users.” — #111499, comentário de revisão

“Organization scoping removed from Group fetch — defense-in-depth weakened.” — #111663, comentário de revisão

“Yeah I think this could be a valid attack since this is the first step in the pipeline. Like what if someone gives us someone else’s installation_id?” — #111728, comentário de revisão

Padrão

As discussões de segurança surgem como cenários de ataque específicos que os revisores identificam — bypass de permissão, verificações de autorização ausentes, defense-in-depth enfraquecida. São observações de alto risco que frequentemente exigem várias rodadas de discussão para resolver. Os PRs de integração com o GitHub (#111728) são particularmente densos em segurança devido à complexidade do pipeline de OAuth.

---

9. Nomenclatura e consistência (11,7%)

Escolhas de nomenclatura, consistência entre APIs e normalização de terminologia.

Evidência

“Possible to have more semantic names for these?” — #111529, comentário de revisão

“I think it would be a good idea to strictly type this, that way developers would get a better typeahead experience + we would probably avoid some subtle naming differences from creeping in.” — #111554, comentário de revisão

“Let’s make sure to pass org_id to the groups query to be safe — nit: rename process_a_column_values to process_column_values.” — #111724, comentário de revisão

Padrão

Embora seja o tema menos frequente, as discussões de nomenclatura quase sempre se repetem entre os PRs. O mesmo padrão de “podemos usar um nome mais semântico/consistente” recorre porque não há convenção de nomenclatura codificada para as áreas em discussão.

---

Análise entre temas

Vários temas coocorrem com frequência:

• Design de API + Gerenciamento de estado: quando os revisores questionam os defaults de API, eles frequentemente também sondam o fluxo de dados que determina esses defaults (visto em #111697)
• Segurança + Gerenciamento de estado: as discussões de pipeline de OAuth envolvem inerentemente tanto preocupações de segurança quanto de fluxo de estado (visto em #111728)
• Evidência de testes + Segurança de tipos: pedidos por testes frequentemente acompanham preocupações de segurança de tipos — “este tratamento de erro é frágil, adicione um teste” (visto em #111691)
• Padrões de componentes + Documentação: “podemos evitar este estilo inline” é tanto um padrão de estilização quanto uma lacuna de documentação — a convenção não está escrita

Essas coocorrências sugerem que um pequeno número de ADRs bem direcionados poderia tratar de múltiplos temas simultaneamente. Consulte Propostas de ADRs para recomendações específicas.