Contribuindo com o pacote vigiar
Source:CONTRIBUTING.md
Obrigado por contribuir! Este documento explica como colaborar com o desenvolvimento do vigiar.
Reportando problemas
Mudancas no portal VIGIAR
Se o dashboard do Power BI mudar e as funcoes pararem de funcionar:
- Verifique se o problema persiste executando
vigiar_conectar(refresh = TRUE) - Rode
vigiar_status()para comparar o esquema atual com o cache - Abra uma issue com o template Schema Change incluindo:
- Data e hora da ultima conexao bem-sucedida
- Mensagem de erro completa
- Tabelas que mudaram (use
vigiar_comparar_schema())
Bug reproducible
Para reportar um bug, inclua um exemplo minimo reproduzivel:
library(vigiar)
vigiar_conectar()
# Codigo minimo que demonstra o problema
dados <- vigiar_baixar("df_anual", limite = 10)
# ...
vigiar_desconectar()Use o template Bug Report e inclua sessionInfo().
Erro de municipio ou codigo IBGE
Se encontrar municipios faltando ou codigos IBGE incorretos:
- Rode
vigiar_rj_municipios()para ver o registro atual - Confirme o codigo no site do IBGE (https://cidades.ibge.gov.br)
- Abra issue com o template Municipio/IBGE
Ambiente de desenvolvimento
Fluxo de trabalho
# 1. Fazer alteracoes no codigo (R/*.R)
# 2. Atualizar documentacao
devtools::document()
# 3. Rodar testes offline
devtools::test()
# 4. Rodar lint
lintr::lint_package()
# 5. Verificar pacote
devtools::check()
# 6. Construir site
pkgdown::build_site()Testes online
Testes que requerem internet sao controlados pela variavel de ambiente VIGIAR_RUN_ONLINE_TESTS. Para roda-los:
Sys.setenv(VIGIAR_RUN_ONLINE_TESTS = "true")
devtools::test()Na CI (GitHub Actions), os testes online sao desligados por padrao.
Adicionando suporte a novo estado
Para expandir alem do RJ:
- Crie um data frame similar a
RJ_MUNICIPIOScom os municipios do estado - Adicione a constante
XX_MUNICIPIOSe funcoes de validacao - Atualize
vigiar_checar_cobertura_espacial()com o novo escopo - Envie um PR com o template Feature Request
Estrutura do pacote
R/
zzz.R Constantes, ambiente interno, utilidades
conexao.R Gerenciamento de sessao
client.R Cliente Power BI (S3)
api.R Construcao e execucao de queries
parse.R Parser do formato DSR
download.R Funcoes de download publicas
classes.R Classes S3 para dados tipados
process.R Processamento e padronizacao
validar.R Validacao de dados
diagnostic.R Diagnostico de qualidade
rj.R Registro de municipios do RJ
series.R Series temporais descritivas
resumo.R Sumarios estatisticos
dictionary.R Dicionario de variaveis
auditar.R Auditoria e compliance
benchmark.R Benchmarks de performance
log.R Logging estruturado
cache.R Cache e snapshots
exportar.R Exportacao (CSV, RDS, Parquet)
tests/testthat/
test-offline.R Testes sem internet
test-online.R Testes com internet
test-new-features.R Testes das features v0.7.0
test-diagnostic.R Testes de diagnostico
data-raw/
dictionary.R Geracao do dicionario
vignettes/
vigiar.Rmd Introducao ao pacote
fluxo-download-processamento.Rmd Fluxo principal
variaveis-vigiar.Rmd Dicionario de variaveis
convencoes-vigiar.Rmd Convencoes
uso-responsavel-dados.Rmd Limitacoes e etica
Convencoes de codigo
- Funcoes exportadas:
vigiar_prefixo, snake_case, sem acentos - Funcoes internas:
.vigiar_prefixo - Classes S3:
vigiar_prefixo (ex:vigiar_tbl,vigiar_diagnostic) - Mensagens usam
cli::para formatacao - Logging usa
.vigiar_log()para registro estruturado
Regras de versionamento
-
Nao versione copias completas do pacote dentro do proprio repositorio. A arvore raiz e a unica fonte de verdade; copias completas (como pastas
vigiar/,vigiar_audit/ouvigiar_repo/) geram ambiguidade e deriva documental. Use branches/tags ou o historico do Git para preservar versoes antigas.