Gracias por el interés. Este documento dice qué esperar y qué se espera, para que una contribución no se pierda por un malentendido de forma.
Antes que nada: el invariante
lupa nunca informa como medido lo que no midió. Un diagnóstico que no pudo correr —falta un paquete opcional, no hay filas suficientes, la comparación se truncó— va a la tabla cobertura_diagnosticos, separada de hallazgos y fuera de la escala de severidad, y su campo de alcance queda en NA, nunca en cero. Un diagnóstico que sí corrió y no encontró nada sale en ok con cero afectados, nunca como sospecha.
De ahí sale casi todo lo demás, así que una contribución que rompa esto no se puede aceptar aunque el código esté bien escrito. Si una propuesta obliga a elegir entre callar y afirmar, la respuesta es una tercera: declarar.
Los otros que rigen:
- La severidad es un factor ordenado
ok < sospechoso < error. -
No hay puntaje global propio.
indice_calidad()devuelve un número sólo si quien lo pide declara los pesos, y viaja con su cobertura, los pesos usados y qué componentes se invirtieron por orientación. -
El perfilado no toca los datos. Ninguna función de análisis altera la tabla que recibe, ni siquiera un
data.table, que R permite modificar por referencia. La capa de remediación produce un plan editable y devuelve una copia. - No se agrega ni se modifica un diagnóstico que sobre los datos objetivo se equivocaría más veces de las que acertaría. Si no se puede medir cuál de los dos casos es más frecuente, el cambio es una apuesta y no entra.
Idioma
La API y la documentación son en español: nombres de funciones, argumentos, valores, mensajes, páginas de ayuda y viñetas. DESCRIPTION, NEWS.md y cran-comments.md van en inglés, porque los lee CRAN. Hay un README.md en inglés y un README.es.md en español, y los dos se mantienen a la par: un cambio en uno sin el otro queda a medias.
Dentro del código R, lo no-ASCII va escapado con \uXXXX. En comentarios y en documentación va UTF-8 normal.
Reportar un defecto
Lo más útil es un ejemplo mínimo reproducible: los datos más chicos que muestren el problema, la llamada exacta, lo que devolvió y lo que esperabas. Si el defecto es una afirmación falsa sobre los datos —que es la clase de defecto que más importa acá— alcanza con mostrar el hallazgo y por qué no es cierto de esa tabla.
Enviar un cambio
Cuatro cosas acompañan a cada cambio, y si alguna no corresponde conviene decir por qué:
- Una prueba que falle si el cambio se revierte. No alcanza con que pase: una aserción que pasaría igual sin el comportamiento que dice probar no prueba nada. La forma barata de comprobarlo es romper el comportamiento a propósito sobre una copia y ver que la prueba se entera.
-
La documentación
roxygende lo que se tocó, regenerada conroxygen2::roxygenise(). - Los dos README, cuando el cambio es visible desde afuera.
- La viñeta que enseña esa capacidad.
Más NEWS.md cuando el cambio se nota al usar el paquete.
Dependencias
Las obligatorias son cli y data.table (esta se llama siempre con data.table::, sin importarla al NAMESPACE). Todo lo demás va en Suggests, y cada uso tiene que tener su rama de ausencia declarada: si el paquete opcional no está, el diagnóstico va a cobertura_diagnosticos con su motivo y su como_resolverlo, no falla ni se saltea en silencio.
El mínimo de R declarado es 4.2.0. Conviene tenerlo presente: funciones posteriores a esa versión no se pueden usar sin más.
Antes de abrir el pull request
Rscript -e 'roxygen2::roxygenise(".")'
R CMD INSTALL --no-multiarch --with-keep.source .
NOT_CRAN=true Rscript -e 'testthat::test_check("lupa")'
Rscript -e 'lintr::lint_dir("R")'
Rscript -e 'spelling::spell_check_package(".")'
R CMD build . && R CMD check --as-cran lupa_*.tar.gzEl orden importa y la forma de correr los tests también. test_dir() y test_file() cargan el paquete con library(lupa), que no expone las funciones internas: la mitad de la suite prueba funciones con punto inicial y da veinte errores falsos de «could not find function». test_check("lupa") es lo que corre R CMD check, y necesita el paquete instalado, por eso el R CMD INSTALL va antes. Si vas a comparar contra cifras publicadas, comprobá además el sello Built de la instalación que estás midiendo: apuntar R_LIBS a un directorio vacío cae en silencio a la biblioteca del usuario y termina midiendo otra versión.
spelling usa inst/WORDLIST, que tiene que dejar la corrida en cero. Las palabras que hay ahí son nombres propios, siglas, términos técnicos y fragmentos de identificadores del paquete; si tu cambio agrega una palabra legítima nueva, agregala al archivo ordenado. Si agrega una que no es legítima, es una errata.
lintr está configurado en .lintr con los linters que el código ya cumple, así que tiene que dar cero avisos. Los que quedan afuera están anotados ahí con su motivo; si te parece que alguno debería entrar, es una conversación aparte del cambio que estés enviando.
Cómo se escribe la documentación
Vale para todo lo que se publica: los 2 README, las viñetas, los artículos y la ayuda. Se escribe para que se lea rápido sin perder precisión.
Voz
-
Viñetas: primera persona del plural («perfilamos la tabla», «veamos qué encontró»).
lupava en tercera persona: el paquete sugiere y quien decide es «nosotros». - README, artículos y ayuda: impersonal («se instala», «devuelve»). Nunca voseo, tuteo ni usted.
-
Inglés (
README.Rmd): «we» en lo que sea recorrido e impersonal en lo demás, con el mismo contenido y el mismo orden que el castellano. - Tildes completas en castellano.
Frases, párrafos y títulos
- Frases de hasta unas 20 palabras. Un párrafo, una idea.
- Lo que enumera 3 o más cosas paralelas va en una lista, no en un párrafo. Para comparar opciones o campos, una tabla.
- Los títulos dicen lo que hay debajo.
Cifras
- Las cantidades van en dígitos: «3 severidades», «2 filas». Quedan en letras:
- «uno» y «una» cuando son artículo o parte de una locución («una columna», «de una vez», «en una sola llamada»);
- los ordinales («la primera llamada»);
- «cero» cuando nombra la idea y no un conteo («nunca cuenta como cero»).
- Ninguna oración empieza con un dígito: se reordena («Hay 3…», «Las 3…»).
- La unidad va separada por un espacio, también en inglés:
30 s, no30s,30 secni30''. En castellano, el porcentaje también:70 %. - Los nombres conservan su forma: los títulos de las guías, las versiones,
ISO/IEC 25012. Los valores literales de los datos no se tocan (-99,"S/D"). - Un recuento que el paquete calcula (tipos de hallazgo, factores de un marco, campos) sale de código en línea, nunca escrito a mano.
- Una cifra de medición (tiempos, consultas, tasas) dice su unidad, su insumo, su entorno, su fecha y el guion que la produce. Sólo se publica si ese guion corrió sobre el código que se publica.
- Un insumo descargado lleva su fuente, su fecha y su suma de control.
- Una cifra ilustrativa se genera en el documento o se borra.
- Una constante del código que la documentación cita es una cifra publicada: se cita como supuesto del código.
Guías en inglés
- Una guía en inglés traduce una guía en castellano y vive sólo en el sitio (
vignettes/articles/, que no viaja en el paquete). - Declara su pareja en el YAML (
pareja:) y está en la sección «Guides in English» de_pkgdown.yml. -
data-raw/comparar-guias.Rcomprueba, antes de construir el sitio, que los 2 lados tengan los mismos trozos, el mismo código y las mismas cifras en línea. Un cambio de código en una guía con pareja se hace en las 2.
Emojis
Hay un juego chico y fijo, y no se agregan otros:
🔎 exploración: qué hace algo, qué trae un hallazgo;
⏱ tiempo y rapidez;
🗄️ tablas y bases de datos;
⚠️ un límite o una advertencia;
📄 el informe;
🧭 el recorrido y el paso siguiente.
Van siempre junto a una palabra, al principio de unos pocos títulos de sección. Nunca solos, ni en medio de un párrafo, ni en código.
Nunca en el título del documento: ni en
title, ni enVignetteIndexEntry, ni enDESCRIPTION.okno lleva una marca de aprobación: la documentación dice queokno es una aprobación, y un tilde verde diría lo contrario.Un título con emoji lleva su ancla explícita (
## ⚠️ Lo que no se pudo evaluar {#lo-que-no-se-pudo-evaluar}). Si un título cambia, su ancla vieja se fija igual, para que los enlaces que apuntaban ahí sigan llegando.
Lo que no aparece
- Nada que cuente cómo se desarrolló el paquete. Ni «antes», «ya no», «se corrigió» o «una versión anterior», ni el proceso que llevó a un cambio: se describe lo que hace hoy.
- Ningún organismo, institución o ciudad que identifique a quien publicó un conjunto de datos real. Sí se nombran los marcos publicados que el paquete implementa (ISO/IEC 25012, CEPAL, AGESIC).
- La protección de datos personales es un complemento: se explica donde corresponde, nunca en el centro.
- La palabra «piso», que tiene 2 sentidos: se dice qué hace en cada caso.
Una viñeta
- Título numerado («3. Explorar columnas con
analizar()»). - La pregunta del lector, en 1 o 2 oraciones.
- Un recuadro «En esta guía:» con 3 a 5 puntos, en la voz «nosotros».
- Un solo caso que hila el relato, con datos del paquete (
datos_operativos,datos_administrativos) o construidos en el fragmento. - A lo sumo unas 25 líneas de prosa antes del primer bloque de código.
- Cierre con
## Resumen(5 puntos como mucho) y## 🧭 Paso siguiente(un enlace).
Código y salidas
- Opciones de knitr:
collapse = TRUE, comment = "#>", yoptions(width = 90)al principio, restaurado al final. - Ninguna salida pasa de 100 caracteres de ancho: las evidencias largas se muestran con
writeLines(strwrap(x, 88))o seleccionando columnas. - Se usan los accesores (
hallazgos(),columnas(),cobertura()), no el acceso con$cuando hay accesor. - Las comprobaciones (
stopifnot()) van en fragmentos conecho = FALSE. - Ninguna salida muestra la fecha o la hora de la compilación, rutas temporales ni tamaños de memoria.
- Las viñetas no usan red ni motores externos (SQLite y DuckDB en memoria sí). Los artículos pueden mostrar código con
eval = FALSEy una salida guardada, siempre con su fuente. - Las viñetas de
vignettes/viajan en el paquete que se envía a CRAN, que las construye en cada chequeo. Un cambio de redacción no puede alargar su construcción.
Enlaces
- Entre viñetas, relativos:
[2. Leer un perfil](leer-un-perfil.html). - A los artículos, absolutos:
https://sebollin.github.io/lupa/articles/<nombre>.html. - A funciones, con el nombre entre comillas invertidas (
`perfilar()`): pkgdown los enlaza solo. - El glosario de
leer-un-perfil.Rmd(leer-un-perfil.html#glosario) define las palabras del paquete, y las demás piezas enlazan ahí. Son, entre otras: alcance, universo, cobertura, vacío por diseño, centinela, severidad, perfil, marco, métrica, plan, granularidad, entidad, atributo e instancia.
Una convención chica que importa
Nombrar es enlazar. En cualquier lugar del repositorio donde se nombre otro paquete o a una persona, va el enlace: al repositorio del paquete o al perfil de quien lo hizo. Vale para el README, la documentación roxygen, las viñetas, NEWS.md e inst/COPYRIGHTS. También para las referencias bibliográficas: si hay DOI o el texto es de acceso libre, va.
