retentioneering/retentioneering-tools

Contribuindo para retentioneering-tools

Objetivo

Converter uma observação de um usuário — um bug, um pequeno problema, uma funcionalidade ausente, uma gambiarra que ele continua reescrevendo — na menor alteração upstream que teria evitado isso, empacotada para que os mantenedores possam aceitá-la rapidamente.

Referências anexadas

Arquivo	Leia quando
references/repo-conventions.md	antes de tocar no código — comandos de build/teste/docs, regras de arquitetura, nomenclatura, obrigações de sincronização
references/proposal-templates.md	ao rascunhar — modelos de issue/feature/PR com exemplos práticos

O caminho completo: ideia → PR mesclado

Estágio 1 — Capture a observação adequadamente (faça isso mesmo para ideias "pequenas")

Registre quatro coisas enquanto estão frescas:

1. Expectativa — o que o usuário acreditava que aconteceria (cite a docstring/página de documentação que criou a expectativa, se houver).
2. Realidade — o que realmente aconteceu (texto de erro exato ou saída incorreta).
3. Custo — tempo perdido, conclusão errada quase lançada, gambiarra escrita.
4. Ambiente — retentioneering.__version__, Python, SO, fonte de instalação (pip wheel vs checkout do source).

Lição de campo: relatórios formatados como expectativa/realidade/custo/reprodução são atendidos; relatórios "X está quebrado" estagnam.

Estágio 2 — Valide contra a versão ATUAL

Muitos pontos de dor já foram corrigidos no v5-migration — verifique antes de rascunhar:

1. git log --oneline -30 e CHANGELOG.md — pesquise palavras-chave da observação.
2. Pesquise issues/PRs existentes: gh issue list --search "<palavras-chave>", gh pr list ....
3. Reproduza no checkout atual (veja Estágio 3). Se não reproduzir mais, a contribuição pode se tornar um esclarecimento de documentação ou um teste de regressão — ambos bem-vindos.

Estágio 3 — Reprodução mínima (o coração de um relatório de bug)

Construa o menor brinquedo que mostra a lacuna, por exemplo:

import pandas as pd
from retentioneering import Eventstream
df = pd.DataFrame({"user_id": ["u1","u1","u2"], "event": ["a","b","a"],
                   "timestamp": pd.date_range("2026-01-01", periods=3, freq="1min")})
# ESPERADO: ...       REAL: ...

Regras: apenas dados sintéticos (nunca o log real do usuário); determinístico (frames fixos, sem aleatoriedade sem semente); um comportamento por reprodução; afirme a expectativa para que a reprodução funcione também como um teste com falha.

Estágio 4 — Escolha o formato da contribuição

Situação	Formato
Defeito claro com reprodução	Issue com reprodução; PR com correção + teste de regressão se o usuário quiser ir além
Comportamento surpreendente, mas documentado	PR de documentação (docstring é a fonte da verdade — as páginas do site são geradas a partir dela)
Funcionalidade ausente	Issue de funcionalidade: caso de uso primeiro, assinatura proposta em segundo, evidência em terceiro (veja modelos)
Gambiarra repetida no código do usuário	Extrair como API proposta: mostre a gambiarra, seu custo, a chamada proposta que a substitui
Armadilha de conclusão errada (biblioteca estava silenciosa)	Enquadrar como "sinal ausente": o que a biblioteca sabia e não revelou; proponha o aviso/campo

Para propostas de API, o enquadramento aceito (dos modelos): problema → evidência de frequência → assinatura proposta → semântica incluindo casos extremos → critérios de aceitação → notas de migração.

Estágio 5 — Implemente (ao fazer um PR, não apenas uma issue)

Leia references/repo-conventions.md primeiro. Itens inegociáveis:

1. Fork ou branch a partir de master rastreando v5-migration; uma alteração lógica por PR.
2. uv sync (ou make install, que também executa npm install), em seguida uv run pre-commit install — uma etapa única por clone que conecta o hook do git para que os commits sejam verificados automaticamente; pule isso e os commits contornam os hooks localmente e o trabalho lint do CI sinaliza a formatação no seu PR. Adicione make build apenas ao mexer em widgets/JS.
3. Siga as convenções de nomenclatura (ADR-0008): path_col/event_col/timestamp_col/session_col, start_event/end_event, processadores com verbo primeiro, widgets com substantivo, gêmeos <widget>_data.
4. Toda execução do DuckDB passa pelo mecanismo de consulta unificado (L1) — sem duckdb.sql ad-hoc com expressões de substituição de varredura (ADR-0002 substituído).
5. Adicione/estenda testes próximos à área de código (tests/...); uma correção de bug DEVE incluir o teste com falha do Estágio 3.
6. Mantenha o padrão de erro alto e útil: erros que listam valores/chaves válidos são o estilo da casa; degradação silenciosa (linhas descartadas, resultados vazios sem sinal) é rejeição automática.
7. Obrigações de sincronização ao renomear/alterar API: a camada de ferramentas MCP espelha os nomes dos métodos do Eventstream; o editor de métricas JS consome o esquema de métricas Python; as docstrings alimentam o site de documentação — atualize tudo no mesmo PR (uv run python docs/scripts/render_pages.py).

Estágio 6 — Pré-voo e envio

uv run pre-commit run --all-files      # ruff lint+format, gitleaks, higiene
uv run pytest tests/ -v                # suíte completa (CI executa 3.11–3.13)
uv run python docs/scripts/render_pages.py   # se docstrings foram alteradas

Estilo de commit: imperativo, com escopo, explicando o PORQUÊ quando não óbvio (veja git log para o estilo da casa). Atualize CHANGELOG.md na seção não lançada/atual para alterações visíveis ao usuário.

Envie:

git push -u origin <branch>
gh pr create --title "<sumário imperativo>" --body-file pr_body.md

Corpo do PR (modelo em references/proposal-templates.md): o que e por que → issue vinculada → reprodução/antes-depois → testes adicionados → checklist de sincronização (docs/MCP/JS se aplicável) → nota de breaking change. CI deve passar: lint + test (3.11/3.12/3.13). master é apenas via PR; mesclar não lança (os lançamentos são orientados por tags pelos mantenedores).

Estágio 7 — Acompanhe

Responda à revisão dentro do PR (evite force-push após o início da revisão; adicione commits). Se os mantenedores pedirem mudanças de direção, atualize a issue primeiro, depois o código — a issue é o contrato.

Modo portfólio: muitas observações de uma vez

Quando o usuário acumulou um lote (por exemplo, um diário de atritos de um projeto): desduplicar → verificar cada uma contra a versão atual (Estágio 2) → classificar por (frequência × risco de falha silenciosa) → arquivar as 3–5 principais como issues separadas com reproduções → oferecer um PR para a correção verificada mais barata para construir credibilidade, referenciando as issues para o restante. Não abra uma mega-issue.