Metodologia

Fontes de dados

Todos os dados são coletados via GitHub CLI (gh) autenticada contra a API do GitHub. Sem scraping, sem serviços de terceiros, sem LLMs no pipeline de dados.

Fase 1: coleta de PRs

Conjunto de dados	Comando de origem	Campos	Contagem
PRs mergeados	gh pr list --state merged	number, title, createdAt, mergedAt, author, reviews, files, labels, url	500
PRs fechados sem merge	gh pr list --state closed --search "is:unmerged"	Mesmos campos	500
PRs abertos	gh pr list --state open	Mesmos campos	251

Para cada PR, o script calcula:

• Tempo até o merge (TTM): (mergedAt - createdAt) em horas
• Eventos de revisão: contagem de revisões CHANGES_REQUESTED, COMMENTED, APPROVED
• Churn: additions + deletions em todos os arquivos alterados
• Domínios de arquivo: primeiros dois segmentos de caminho de cada arquivo alterado (ex.: src/sentry → domínio src/sentry)
• Escopo do título: extraído do formato de conventional commit type(scope): description
• Rodadas de revisão: contagem de eventos CHANGES_REQUESTED (proxy para ciclos de idas e vindas)
• Score de atrito: composto normalize(review_events) + normalize(TTM), em que normalize mapeia para o intervalo 0-1 via escalonamento min-max

Fase 2: coleta aprofundada de comentários

Para os 50 PRs mergeados de maior score de atrito e os 10 PRs fechados sem merge com maior volume de discussão:

1. Comentários no nível da issue via gh pr view N --json comments — discussão geral sobre o PR
2. Corpos de revisão via gh pr view N --json reviews — resumos de revisão de nível superior
3. Comentários de revisão inline via gh api repos/{owner}/{repo}/pulls/N/comments --paginate — comentários de revisão de código no nível da linha

Total coletado: 965 comentários em 60 PRs, dos quais 604 são não-bot.

Comentários de bots como sinal de primeira classe

Os comentários de revisão de bots não são descartados. O Sentry usa ferramentas de revisão automatizada de forma extensiva (sentry[bot], sentry-warden[bot], cursor[bot]), e essas revisões causam atrito real para os desenvolvedores — elas precisam ser lidas, avaliadas e atendidas ou descartadas. Analisamos a atividade de revisão dos bots como uma dimensão separada na página de Atrito de revisão automatizada.

Filtramos sim o ruído automatizado (relatórios de falha de CI, comentários de linkback do Linear, resumos de template BUGBOT_REVIEW do Cursor) por marcador de conteúdo — esses são metadados não substantivos, não trabalho de revisão. Após a filtragem, os comentários de bot restantes são achados substantivos no nível da linha que o desenvolvedor precisa atender.

Fase 3: codificação de temas

Os comentários são classificados usando um dicionário de temas baseado em palavras-chave (theme_dictionary.json). Trata-se de uma abordagem determinística e auditável:

1. Filtrar comentários de bots e mensagens automatizadas (links do Linear, relatórios de falha de CI, revisões do Bugbot do Cursor)
2. Filtrar comentários com menos de 20 caracteres
3. Para cada comentário restante, verificar quais palavras-chave de tema aparecem no corpo
4. Registrar citações correspondentes como evidência (primeiros 300 caracteres)

O dicionário de temas é externalizado como JSON para que possa ser revisado, contestado e refinado independentemente do código de análise.

Seleção de amostra

Janela de PRs mergeados

PRs mergeados nos últimos 90 dias, limitados aos 500 mais recentes. Isso captura a cultura de revisão atual do Sentry em vez de padrões históricos.

Seleção de comentários aprofundada

Os 50 principais por score composto de atrito em vez de uma única dimensão. Isso evita supervalorizar PRs lentos-mas-silenciosos ou rápidos-mas-barulhentos. O score de atrito combina:

• Contagem normalizada de eventos de revisão (0-1)
• TTM normalizado (0-1)

Um PR que é tanto muito discutido QUANTO lento para mergear fica no topo do ranking.

Extensão para fechados sem merge

500 PRs fechados sem merge na mesma janela, mais comentários aprofundados para os 10 principais por volume de discussão. Eles representam tentativas de consenso abandonadas.

Limitações

Viés de merge

As métricas de baseline são calculadas apenas a partir de PRs mergeados. PRs fechados sem merge ou que permanecem parados são analisados separadamente, mas não incluídos na baseline. Isso significa que a baseline subestima o atrito total de revisão.

Limites da API do GitHub

gh pr list retorna no máximo 500 PRs por consulta. Para um repositório tão ativo quanto o Sentry, 500 PRs mergeados cobrem aproximadamente 2-3 semanas de atividade, não a janela completa de 90 dias. A amostra é enviesada em direção a PRs mais recentes.

Codificação de temas por palavra-chave

A classificação de temas usa correspondência de palavras-chave, não compreensão semântica. Isso significa:

• Falsos positivos: um comentário contendo “default” pode ser sobre um default de CSS, não sobre defaults de API
• Falsos negativos: discussões que usam sinônimos ou linguagem indireta podem ser perdidas
• Sem sentimento: contamos a presença de temas, mas não se a discussão foi conflituosa ou rotineira

O dicionário de temas foi inicializado lendo uma amostra de comentários reais e iterando sobre as listas de palavras-chave. Ele é publicado para revisão e pode ser refinado.

Eventos de revisão vs. discussão real

Os eventos de “review” do GitHub incluem APPROVED, COMMENTED e CHANGES_REQUESTED. Um PR com 10 revisões APPROVED tem a mesma contagem de revisões que um com 10 CHANGES_REQUESTED. A análise aprofundada de comentários compensa parcialmente ao examinar o conteúdo real dos comentários nos PRs de alto atrito.

Prevalência de comentários de bots

Os PRs do Sentry incluem atividade significativa de bots (Bugbot do Cursor, linkback do Linear, relatórios de falha de CI). Eles são filtrados da análise de temas, mas inflam as contagens brutas de eventos de revisão nas métricas de baseline. Sinalizamos bots por sufixo de login ([bot], -bot) e por marcadores de conteúdo, mas algumas mensagens automatizadas de contas não-bot podem passar.

Escassez de labels

Os PRs do Sentry usam primariamente apenas as labels Scope: Backend e Scope: Frontend. O mapa de atrito por domínio depende mais fortemente da análise do escopo do título e dos prefixos de caminho de arquivo do que das labels.

Reprodutibilidade

O pipeline completo pode ser reproduzido com:

# Requires: Python 3.11+, GitHub CLI (gh) authenticated
cd studies/sentry-pr-review-friction

# Phase 1 + 2: Collect data (~2 minutes for deep comments)
python analyze_sentry_prs.py collect --repo getsentry/sentry --days 90 --limit 500

# Phase 3: Analyze
python analyze_sentry_prs.py analyze

# Phase 4: Generate narrative data
python analyze_sentry_prs.py report

Todos os artefatos JSON são gravados em output/ com timestamps e metadados de metodologia.