Gobernanza en CI
Unos 40 minutos de lectura, con 10 ejemplos en 14 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.31. Lee el original
En esta página
- Ejecuta todas las comprobaciones como un solo trabajo
- Haz que el pull request sea la puerta de control, no el commit
- Informe de lo que alcanza un cambio de esquema
- Pide la aprobación del propietario antes de bajar una clasificación
- Deprecar una columna antes de eliminarla
- Enruta las revisiones de cada dominio por ruta
- Superponer las reglas de dominio sobre las reglas globales
- Contar los hallazgos exceptuados por verificación
- Qué sale mal en producción
- Una comprobación que lee cada fila
- Una verificación que marca cada ID
- Un archivo roto se convierte en un hallazgo
- Otros fallos
- Lo que decidió este capítulo
Al final de este capítulo podrás ejecutar las comprobaciones de gobernanza de los capítulos 2 a 7 como un solo trabajo en cada pull request, juzgando únicamente lo que el pull request cambia. Falla cuando una columna no tiene clasificación, ejecuta las pruebas de la política de acceso y de la capa de aplicación, informa de a qué llega aguas abajo cada cambio de esquema, y aplica dos reglas que los verificadores de cambios incompatibles no cubren. Los verificadores de cambios incompatibles son las herramientas que comparan dos versiones de un esquema en busca de cambios que rompan a sus lectores. Mantendrás la propiedad en contratos del Open Data Contract Standard (ODCS), generados a partir de los metadatos, con una carpeta y un responsable de código por dominio, aplicarás las reglas de cada dominio sobre las globales, y medirás el ruido de cada comprobación por los hallazgos que nadie atiende.
Los capítulos anteriores construyeron las comprobaciones de gobernanza de una plataforma de aprendizaje en línea cuyos equipos cambian sus esquemas cada semana, y ningún pull request ejecuta ninguna de ellas. El capítulo 2 prueba el catálogo contra los metadatos revisados, y el capítulo 4 lee el linaje de cada ejecución de pipeline. El capítulo 5 prueba la política de acceso, y el capítulo 6 prueba la capa que la aplica en las consultas. El capítulo 7 genera propiedades de tabla a partir de las clasificaciones. Cada una se ejecuta solo cuando alguien ejecuta su ejemplo, nunca cuando un equipo cambia la plataforma. Vienen tres cambios. El equipo de CRM quiere una columna para el correo de trabajo de los estudiantes, el equipo de aprendizaje quiere renombrar una columna que leen los pipelines de reporting, y el equipo de ciencia de datos quiere ver las ciudades de los estudiantes sin máscara. Cada uno es un cambio pequeño que un revisor aprobaría, y cada uno modifica lo que se rompe o quién ve qué.
Este capítulo añade el módulo compartido del libro para detectarlos, lib.ci, que es el trabajo de gobernanza de la plataforma. En este capítulo, el job es este job de CI, no uno de OpenLineage. Cada pull request simulado se ejecuta sin conexión, como dos carpetas llamadas checkouts, una de la rama principal y otra de la rama del pull request. Cada una contiene governance/, los archivos de gobernanza de la plataforma; pipelines/, el SQL de sus pipelines; migrations/, las sentencias alter table con las que una rama cambia esquemas, que lib.ci.migrate aplica como cambios de esquema de Iceberg; y los archivos generados a partir de los metadatos. Para cada lado, lib.ci.build construye una plataforma temporal tal como funciona la plataforma: las tablas de origen, las migraciones de ese lado, el despliegue, que escribe los metadatos en el catálogo y establece las propiedades generadas de cada tabla, y después la ejecución nocturna de los pipelines de ese lado, con linaje. Entre esos pipelines, review_corpus se mantiene como la copia sin gobernanza del capítulo 4, de modo que el trabajo sigue comprobando su linaje; la plataforma entrena con la compilación gobernada del capítulo 9. lib.ci.run ejecuta las comprobaciones y compara los dos lados. No intervienen git ni la red, y cada fecha se compara con el "hoy" del libro, 1 de octubre de 2026, nunca con el reloj.
Ejecuta todas las comprobaciones como un solo trabajo
Una comprobación que se ejecuta cuando alguien se acuerda de ella es un informe, y los informes no se leen. En una solicitud de cambios, una comprobación es una puerta: se ejecuta con cada cambio, antes de que el cambio se fusione, y hace fallar la solicitud mediante su código de salida. Así recomienda Open Policy Agent (OPA) ejecutar sus políticas en CI, con las opciones --fail y --fail-defined, que fijan el código de salida en 1 según los resultados de las consultas (documentación de OPA sobre CI/CD). Un trabajo formado por varias comprobaciones necesita además cuatro cosas:
- Cada comprobación se ejecuta e informa de todos sus hallazgos, de modo que un fallo no oculte el siguiente. Una comprobación que se bloquea se convierte en un solo hallazgo, "la comprobación no pudo ejecutarse", que hace fallar el trabajo mientras las demás comprobaciones siguen ejecutándose.
- Cada hallazgo tiene un ID estable, de modo que el mismo problema tenga el mismo nombre en cada ejecución y pueda discutirse, contarse y excepcionarse.
lib.cilo escribe como la comprobación y el sujeto, comocoverage/crm.learners.work_email. - El trabajo juzga lo que cambia la solicitud de cambios. Ejecuta también las comprobaciones de la rama principal y compara ambos resultados. Un hallazgo que introduce la solicitud hace fallar la solicitud. Un hallazgo que ya está en main se informa en cada ejecución, se cuenta y se nombra junto con el equipo que lo posee, pero no hace fallar ninguna solicitud que lo deje como está. Juzgamos que una comprobación que hace fallar cada solicitud por hallazgos que nadie en ella provocó acaba desactivada. La plataforma de análisis de código de Google, Tricorder, muestra por defecto los resultados de la mayoría de sus análisis solo en las líneas que toca un cambio (Sadowski et al., 2015).
- La lista de comprobaciones vive en un archivo revisado,
governance/ci.toml, de modo que desactivar una de ellas sea un cambio que alguien aprueba.
El trabajo de la plataforma ejecuta estas comprobaciones, en este orden:
| Comprobación | Desde | Falla cuando |
|---|---|---|
coverage |
Capítulos 2 y 3 | Una tabla no tiene metadatos ni propietario, o una columna no tiene clasificación o tiene una inferior a la sugerida por su nombre |
contract-rules |
Este capítulo | Un contrato rompe una regla global o de dominio |
contracts |
Este capítulo | Un archivo generado está desactualizado |
policy-tests |
Capítulo 5 | Falla una prueba de Rego o una fila de quién-ve-qué |
enforcement-tests |
Capítulo 6 | Falla un caso de regresión o una consulta de quién-ve-qué |
migrations |
Este capítulo | Iceberg rechaza una migración |
pipelines |
Capítulo 4 | Un pipeline no puede ejecutarse, o su linaje no puede leerse |
lineage-classifications |
Capítulo 4 | Una columna está declarada con menos protección de la que propone el linaje |
owner-review |
Este capítulo | Una clasificación baja, o cambia un propietario o un dominio sin aprobación |
removals |
Este capítulo | Se elimina una columna antes de haberla marcado como obsoleta |
properties |
Capítulo 7 | A una tabla le faltan las propiedades generadas para ella |
La primera solicitud de cambios que ve el trabajo es la del equipo de CRM. Los empleadores compran licencias de equipo para su personal, así que el equipo añade work_email a crm.learners en una sola migración y olvida los metadatos de la columna:
1"""The platform's governance job on one pull request, run as a CI step runs it: the CRM team adds a work email to2crm.learners. The prose's point rests on the coverage finding for the new column and on the exit code the step returns."""34from lib import ci5from lib.platform import scratch67main = ci.checkout() # the main branch: governance files, pipelines and the files generated from them8branch = ci.checkout(main) # the pull request's branch, starting from main9(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")10print("files the pull request changes:", ", ".join(ci.changed(main, branch)))1112# What a CI step runs, `python -m lib.ci MAIN BRANCH --summary FILE`: it prints the report and its totals, writes the13# report as Markdown for the pull request, and exits with the code it returns.14summary = scratch() / "summary.md"15code = ci.main([str(main), str(branch), "--summary", str(summary)]) # 1 when a finding this pull request adds fails it16print("the step exits with:", code)17print("the summary it writes for the pull request:")18print(summary.read_text(encoding="utf-8"), end="")
python governance-ci-report.pyfiles the pull request changes: migrations/0001-add-work-email.sql
coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
contract-rules: passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked
contracts: passed, findings 0, new 0, on main 0, waived 0, 11 files checked
policy-tests: passed, findings 0, new 0, on main 0, waived 0, 24 tests and rows checked
enforcement-tests: passed, findings 0, new 0, on main 0, waived 0, 44 cases checked
migrations: passed, findings 0, new 0, on main 0, waived 0, 1 migrations checked
pipelines: passed, findings 0, new 0, on main 0, waived 0, 4 pipelines checked
lineage-classifications: passed, findings 0, new 0, on main 0, waived 0, 23 columns checked
owner-review: passed, findings 0, new 0, on main 0, waived 0, 77 columns checked
removals: passed, findings 0, new 0, on main 0, waived 0, 87 columns checked
properties: passed, findings 4, new 0, on main 4, waived 0, 12 tables checked
coverage/ai.review_corpus: no metadata; on main, owner team-platform
coverage/crm.learners.work_email: not classified; its name suggests personal
coverage/marketing.audience: no metadata; on main, owner team-platform
properties/ai.review_corpus: 7 of 7 generated properties missing; on main, owner team-platform
properties/analytics.course_performance: 4 of 4 generated properties missing; on main, owner team-analytics
properties/analytics.learner_activity: 4 of 4 generated properties missing; on main, owner team-analytics
properties/marketing.audience: 7 of 7 generated properties missing; on main, owner team-platform
change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
job: failed
checks run: 11
checks failed: 1
findings: 7
findings the pull request introduces: 1
findings already on main: 6
findings waived: 0
findings approved: 0
exit code: 1
the step exits with: 1
the summary it writes for the pull request:
## Governance job: failed
| Check | Result | New | On main | Waived | Checked |
| --- | --- | ---: | ---: | ---: | --- |
| `coverage` | failed | 1 | 2 | 0 | 12 tables |
| `contract-rules` | passed | 0 | 0 | 0 | 10 contracts |
| `contracts` | passed | 0 | 0 | 0 | 11 files |
| `policy-tests` | passed | 0 | 0 | 0 | 24 tests and rows |
| `enforcement-tests` | passed | 0 | 0 | 0 | 44 cases |
| `migrations` | passed | 0 | 0 | 0 | 1 migrations |
| `pipelines` | passed | 0 | 0 | 0 | 4 pipelines |
| `lineage-classifications` | passed | 0 | 0 | 0 | 23 columns |
| `owner-review` | passed | 0 | 0 | 0 | 77 columns |
| `removals` | passed | 0 | 0 | 0 | 87 columns |
| `properties` | passed | 0 | 4 | 0 | 12 tables |
### To fix in this pull request
- `coverage/crm.learners.work_email`: not classified; its name suggests personal
### Already on main, and whose it is
- `coverage/ai.review_corpus`: no metadata (team-platform)
- `coverage/marketing.audience`: no metadata (team-platform)
- `properties/ai.review_corpus`: 7 of 7 generated properties missing (team-platform)
- `properties/analytics.course_performance`: 4 of 4 generated properties missing (team-analytics)
- `properties/analytics.learner_activity`: 4 of 4 generated properties missing (team-analytics)
- `properties/marketing.audience`: 7 of 7 generated properties missing (team-platform)
### Schema changes
- `crm.learners`, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
La solicitud introduce 1 hallazgo, y es el que hace fallar el trabajo: crm.learners.work_email es not classified; its name suggests personal. La sugerencia procede de las reglas de nombres del capítulo 3, que coinciden con e_?mail, así que el hallazgo indica qué añadir. De las comprobaciones del trabajo, 1 falla, y el paso termina con el código 1. Los hallazgos de cobertura en main son marketing.audience y ai.review_corpus, las tablas que nadie ha descrito desde que las encontró el capítulo 2. Ninguna de las dos tablas tiene propietario, así que el trabajo nombra al equipo de plataforma, que ci.toml hace responsable de las tablas que nadie posee. El linaje del capítulo 4 muestra que ambas contienen datos personales, y cada informe las repite hasta que alguien las describa.
Las demás comprobaciones pasan, entre ellas las pruebas de políticas del capítulo 5, que se ejecutan sobre los datos que generan los archivos de la rama, y las pruebas de aplicación del capítulo 6, que se ejecutan sobre las tablas de la rama. La comprobación de propiedades informa de hallazgos en main, como 4 of 4 generated properties missing; on main, owner team-analytics: las tablas que escriben los pipelines pierden sus propiedades generadas en cada ejecución nocturna, como encontró el capítulo 7, tanto en main como en la rama. El cambio de esquema, added as work_email string; named by 0 pipelines, reaches 0 columns, todavía no afecta a nada.
Regla práctica: Ejecuta todas las comprobaciones como un solo trabajo en cada solicitud de cambios, cada una informando de todos sus hallazgos con IDs estables, y trata una comprobación bloqueada como un hallazgo que hace fallar. Haz fallar el trabajo por código de salida ante cualquier hallazgo que introduzca la solicitud y que no esté excepcionado ni aprobado. Informa de cada hallazgo que ya esté en main, contado y nombrado con su propietario, sin hacer fallar una solicitud que lo deje como está. Mantén la lista de comprobaciones en un archivo revisado.
Haz que el pull request sea la puerta de control, no el commit
El trabajo de la plataforma se ejecuta en CI. Un hook de pre-commit es el otro lugar donde puede ejecutarse una comprobación, en la máquina del autor, antes de que exista un commit. pre-commit, un marco para hooks de git, que normalmente los ejecuta solo sobre los archivos que cambia un commit, y su documentación presenta los hooks como una forma de detectar problemas simples antes de la revisión de código (pre-commit). Eso encaja con comprobaciones que necesitan un solo archivo: que metadata.toml se analice correctamente, y que cada clasificación sea uno de los cuatro valores.
No encaja con la comprobación de cobertura. El pull request del equipo de CRM cambió migrations/0001-add-work-email.sql y ningún archivo de metadatos, así que un hook filtrado a archivos de metadatos no habría tenido nada que comprobar. El hueco está entre el catálogo, que la migración cambió, y un archivo que el pull request nunca tocó, y solo un trabajo que construya el catálogo completo lo detecta. Un hook puede configurarse para ejecutarse de todos modos, con la variable always_run de pre-commit, de modo que se ejecute incluso cuando ningún archivo coincide. Pero solo se ejecuta donde alguien lo instaló, y cualquiera puede saltárselo, con la variable SKIP de pre-commit o con --no-verify de git, y ningún revisor puede verlo.
Por eso la puerta de control es el trabajo en el pull request, marcado como obligatorio. La protección de ramas de GitHub puede exigir que todas las comprobaciones de estado requeridas pasen antes de que los colaboradores puedan fusionar cambios en la rama protegida (GitHub, ramas protegidas), y un estado que no es obligatorio es solo una recomendación. Dónde aparecen los resultados importa tanto como eso. Los autores de Tricorder de Google descubrieron que el uso del análisis disminuye cuando los desarrolladores tienen que abrir un panel o ejecutar una herramienta de línea de comandos aparte (Sadowski et al., 2015). Se trata de una empresa y de análisis de código, no de datos, pero es la razón por la que lib.ci.main hace más que devolver el código de salida. Un paso de CI lo ejecuta como python -m lib.ci MAIN BRANCH, e imprime una línea por cada hallazgo, con su ID y lo que hay que añadir. También escribe el informe en Markdown para el pull request, donde el revisor lee el diff. Publicar el resumen, y leer las aprobaciones desde las revisiones del pull request, son parte del servicio de CI y quedan fuera del alcance de este libro.
Regla práctica: Usa los hooks para comprobaciones rápidas de archivos individuales en la máquina del autor, y haz que el trabajo de CI en el pull request sea la puerta de control, exigido por la protección de ramas de la rama principal. Pon cada hallazgo en el propio pull request, con su ID y lo que hay que hacer al respecto, nunca solo en un panel. Ejecuta también sus comprobaciones de forma programada contra el catálogo de producción, para las tablas que cambian fuera de cualquier pull request.
Informe de lo que alcanza un cambio de esquema
La columna que añadió el equipo de CRM no llegó a nada downstream, pero un cambio de nombre sí llega, y sus tres tipos de lectores, Iceberg, SQL y los metadatos de gobernanza, lo juzgan de forma distinta. Los lectores de Iceberg encuentran las columnas por ID de campo, y la especificación dice que "la proyección debe hacerse usando field ids" (especificación de tablas Iceberg, 1.12.0), así que una columna renombrada sigue leyendo cada archivo escrito antes del cambio de nombre. SQL encuentra las columnas por nombre, de modo que el mismo cambio de nombre rompe cada consulta y cada pipeline que nombra la columna. Los metadatos de gobernanza de la plataforma están indexados por ID de campo, como decidió el capítulo 2, así que un cambio de nombre solo necesita actualizar el nombre junto al ID. Las promociones de tipo primitivo válidas de la especificación son int a long, float a double, y la precisión de un decimal, que solo puede ampliarse, además, en el formato v3, de date a timestamp o a timestamp_ns, y una columna de tipo unknown a cualquier tipo. Cualquier otro cambio exige una columna nueva.
Qué SQL rompe un cambio es una cuestión de linaje, y el capítulo 4 la respondió recorriendo el grafo de columnas. Una revisión tiene que seguir también las aristas INDIRECT, el nombre que el capítulo 4 da a las entradas que deciden qué filas contiene una salida en lugar de cuáles son sus valores. La faceta de linaje de columnas de OpenLineage guarda una lista de dataset para el linaje de columnas que afecta a todo el conjunto de datos, mediante filtrado, ordenación, agrupación, uniones, funciones de ventana y similares (ColumnLineageDatasetFacet, 1.54.0). Una columna usada solo para unir o agrupar da forma a cada fila a la que alimenta, algo que un informe de valores copiados no detecta. lib.ci.changes compara los esquemas de ambos lados campo por campo, por ID de campo. Para cada columna que la rama renombra, cambia de tipo o elimina, recorre el grafo de linaje de la rama main (la rama principal): los pipelines cuyo SQL nombra la columna, las columnas cuyos valores provienen de ella, cada columna que puede cambiar y los equipos que las poseen.
Después viene el cambio de nombre que hizo el equipo de aprendizaje de learning.courses.category a subject, tanto en una migración como en el archivo de metadatos. El mismo pull request también corrige los dos pipelines que nombran la columna:
1"""What the learning team's rename of learning.courses.category reaches, through Iceberg readers, SQL and lineage. The2prose's point rests on the courses an Iceberg reader still finds, the columns reached, and the job's verdict once the fix merges with the rename."""3import pyarrow.compute as pc45from lib import ci, retention67main = ci.checkout()8branch = ci.checkout(main)9(branch / "migrations" / "0001-rename-category.sql").write_text(10 "alter table learning.courses rename column category to subject;\n")11ci.edit(branch, "governance/metadata.toml", '3 = { name = "category", classification = "public"',12 '3 = { name = "subject", classification = "public"') # the same field ID, renamed1314before, after = ci.build(main), ci.build(branch)15# matched by field ID, so the rename is one change, not a column dropped and another added16change = next(c for c in ci.changes(before, after) if c.table == "learning.courses")17print("change:", change.kind, "from", change.before, "to", change.after)18print("field ID, before and after:", change.field_id)19# read by the new name: Iceberg maps it to the same field ID as before20subjects = after.catalog.load_table("learning.courses").scan(selected_fields=("subject",)).to_arrow()21print("courses whose subject an Iceberg reader finds:", pc.count(subjects["subject"]).as_py())22print("pipelines whose SQL names it:", ", ".join(change.jobs))23for job, why in sorted(after.failed.items()):24 print(f"pipeline {job}, on the branch:", why)25print("columns whose values come from it:", len(change.values))26for column in change.values:27 print(" value of:", column)28print("columns it can change, DIRECT and INDIRECT:", len(change.reached))29# a column's table is the first two parts of its name, schema.table.column30print("tables those columns are in:", ", ".join(sorted({".".join(c.split(".")[:2]) for c in change.reached})))31print("owners the report goes to:", ", ".join(change.owners))32print("tables on main:", len(retention.tables(before.catalog)))33print("tables on the branch:", len(retention.tables(after.catalog)))34coverage = ci.run(before, after, checks=["coverage"]).checks[0]35print("coverage findings on the branch:", ", ".join(finding.id for finding in coverage.findings))3637# The same pull request, with both pipelines changed to read the new name. Each side runs its own pipelines/.38ci.edit(branch, "pipelines/course_performance.sql", " c.category,", " c.subject as category,")39ci.edit(branch, "pipelines/course_performance.sql", "c.title, c.category", "c.title, c.subject")40sql = (branch / "pipelines" / "marketing_audience.sql").read_text(encoding="utf-8")41(branch / "pipelines" / "marketing_audience.sql").write_text(sql.replace("c.category", "c.subject").replace(42 "f.category", "f.subject"), encoding="utf-8")43fixed = ci.build(branch)44ci.generate(fixed) # and the contracts generated again, as the author's hook would45print("files the fixed pull request changes:", ", ".join(ci.changed(main, branch)))46for line in ci.lines(ci.run(before, fixed, checks=["pipelines", "coverage", "contracts", "lineage-classifications"])):47 print("with the fix,", line)
python schema-change-impact.pychange: renamed from category string to subject string
field ID, before and after: 3
courses whose subject an Iceberg reader finds: 200
pipelines whose SQL names it: course_performance, marketing_audience
pipeline course_performance, on the branch: Unknown column: category
pipeline marketing_audience, on the branch: Unknown column: category
columns whose values come from it: 2
value of: analytics.course_performance.category
value of: marketing.audience.favourite_category
columns it can change, DIRECT and INDIRECT: 12
tables those columns are in: analytics.course_performance, marketing.audience
owners the report goes to: no owner, team-analytics
tables on main: 12
tables on the branch: 10
coverage findings on the branch: coverage/ai.review_corpus
files the fixed pull request changes: governance/contracts/learning/courses.odcs.yaml, governance/metadata.toml, migrations/0001-rename-category.sql, pipelines/course_performance.sql, pipelines/marketing_audience.sql
with the fix, pipelines: passed, findings 0, new 0, on main 0, waived 0, 4 pipelines checked
with the fix, coverage: passed, findings 2, new 0, on main 2, waived 0, 12 tables checked
with the fix, contracts: passed, findings 0, new 0, on main 0, waived 0, 11 files checked
with the fix, lineage-classifications: passed, findings 0, new 0, on main 0, waived 0, 23 columns checked
with the fix, coverage/ai.review_corpus: no metadata; on main, owner team-platform
with the fix, coverage/marketing.audience: no metadata; on main, owner team-platform
with the fix, change learning.courses, field 3: renamed from category string to subject string; named by 2 pipelines, reaches 12 columns
with the fix, job: passed
Para Iceberg, nada se rompió. El cambio de nombre conservó el ID de campo de la columna, así que un lector Iceberg en la rama sigue encontrando un subject para 200 cursos. Para SQL, los pipelines que nombran la columna, course_performance, marketing_audience, se detienen cada uno antes de escribir nada en la rama, porque el capítulo 4 convirtió en error el linaje ilegible. A través de valores, el cambio de nombre alcanza 2 columnas, las dos copias de la categoría. A través de cada arista alcanza 12 columnas, cada columna de analytics.course_performance, marketing.audience, porque las categorías agrupan el informe de cursos y clasifican la categoría favorita de cada alumno. El informe va para no owner, team-analytics: el equipo de analítica, y nadie para marketing.audience, que todavía no tiene propietario.
Una compilación rota oculta lo que rompe. El catálogo de la rama contiene 10 tablas, frente a 12 en main, porque los pipelines rotos no escribieron nada. La cobertura informa solo de coverage/ai.review_corpus: una tabla que no existe no puede encontrarse sin descripción, así que el hallazgo de marketing.audience desaparece. Cada lado ejecuta su propio pipelines/, así que la corrección viaja con el cambio de nombre: con ambos pipelines leyendo subject, el trabajo informa passed. En producción, la fusión también puede proteger lo que vio la revisión. Un commit al catálogo REST puede llevar AssertCurrentSchemaId, que exige que el ID de esquema actual de la tabla coincida con el que nombra el requisito (especificación del catálogo REST, 1.12.0), así que una migración revisada contra un esquema falla en lugar de aplicarse a otro.
Regla práctica: Compara esquemas por ID de campo, nunca por nombre ni por ID de esquema, e informa de cada cambio de nombre, cambio de tipo y eliminación de tres formas: si se ven afectados los lectores de Iceberg, qué pipelines cuyo SQL nombra la columna, y qué alcanza a través del linaje, incluidas las aristas INDIRECT. Envía el informe a los propietarios de cada tabla que alcance. Fusiona un cambio de nombre que rompa un pipeline en el mismo pull request que la corrección del pipeline, nunca antes.
Pide la aprobación del propietario antes de bajar una clasificación
Los verificadores de cambios incompatibles protegen a los lectores de un esquema. Las restricciones de modelo de dbt marcan la eliminación de una columna, o el cambio de su tipo de dato, como cambios incompatibles que podrían afectar a los consumidores posteriores (restricciones de modelo de dbt). El comando breaking de datacontract-cli compara dos contratos ODCS y rechaza un cambio que rompe una garantía en la que confían los consumidores (datacontract-cli 1.2.7). Ninguno de los dos trata la protección como una garantía. En datacontract-cli 1.2.7, ninguna regla cubre la clasificación de una propiedad ni el rol de una persona del equipo, así que un cambio en cualquiera de los dos recae en una regla que lo marca como no probado (rules.py). El detector informa de un cambio así con el nivel INFO (detector.py), un nivel que no falla. El comando termina con código 1 solo para las entradas ERROR (comando de cambios incompatibles, modelo de cambios incompatibles). examples/requirements.txt no lo fija, así que ningún ejemplo lo ejecuta. El 22 de octubre de 2026, datacontract-cli 1.2.7, ejecutado sobre los contratos que este capítulo genera para crm.learners, falló una email renombrada con código de salida 1. Interpretó el cambio de nombre como una eliminación, aunque la propiedad conservó su id, porque compara las propiedades por nombre (normalize.py). Aprobó email reclasificada de personal a public, y un cambio de propietario, con código de salida 0. El propio ODCS dice que una clasificación «Can be anything» (puede ser cualquier cosa) (esquema ODCS v3.2.0).
Sin embargo, toda política lee la clasificación, así que bajarla está entre los cambios de mayor consecuencia que puede contener un archivo de metadatos. Añadimos una primera regla propia: bajar la clasificación de una columna, cambiar el propietario de una tabla o mover una tabla a otro dominio requiere la aprobación del equipo que es propietario de la tabla en la rama principal. Un traslado cuenta como cambio de propiedad, porque las reglas propias de un dominio se aplican a sus tablas (una sección posterior). El propietario se toma de la rama principal, porque de otro modo una solicitud de cambios podría asignar una tabla a un nuevo propietario, y ese nuevo propietario podría aprobar la bajada de clasificación. El capítulo 2 fijó la misma regla para los borradores de un modelo: solo un revisor baja una clasificación, y el motivo consta en la descripción de la columna.
La solicitud de cambios del equipo de ciencia de datos llega al final. Baja crm.learners.city de personal a internal, para que los científicos de datos puedan agrupar a los estudiantes por ciudad. La política de acceso seudonimiza las columnas personales para los científicos de datos, y la bajada saca city de esa regla. La ejecución consulta la política antes y después, luego ejecuta las comprobaciones que revisan esquemas y políticas, y la regla del propietario:
1"""A pull request from the data-science team lowers crm.learners.city from personal to internal. The prose's point rests2on analyst-1's mask on each side, and on the owner rule failing alone."""3from lib import ci, policy45main = ci.checkout()6branch = ci.checkout(main)7ci.edit(branch, "governance/metadata.toml", '6 = { name = "city", classification = "personal"',8 '6 = { name = "city", classification = "internal"')9before, after = ci.build(main), ci.build(branch)1011reading_city = policy.request("analyst-1", "crm.learners", ["learner_id", "city"])12for side, name in ((before, "main"), (after, "the branch")):13 rego = policy.interpreter(side.governance / "policies", data=ci.policy_data(side))14 # a column with no mask in the decision is shown as it is stored15 print(f"analyst-1 reading city, on {name}:", policy.decide(reading_city, rego)["column_masks"].get("city", "unmasked"))1617checks = ["policy-tests", "enforcement-tests", "removals", "owner-review"]18report = ci.run(before, after, checks=checks)19print("schema changes:", len(report.changes))20for line in ci.lines(report):21 print(line)2223# The approvals come from the pull request's reviews: one entry per approving review, named by the reviewer's team.24# The owner rule passes when it raises no unapproved finding.25owner_review = lambda approvals: "passed" if ci.run(before, after, approvals, checks=["owner-review"]).passed else "failed"26print("owner-review, once team-crm approves:", owner_review(["team-crm"]))27print("owner-review, once team-analytics approves:", owner_review(["team-analytics"]))28ci.edit(after.root, "governance/ci.toml", "teams = {}", "teams = { team-crm = 2 }") # team-crm asks for two29# one approval from team-crm and one from another team: team-crm still needs a second of its own30print("owner-review, two required, one from team-crm:", owner_review(["team-crm", "team-platform"]))31print("owner-review, two required, two from team-crm:", owner_review(["team-crm", "team-crm"]))
python classification-downgrade.pyanalyst-1 reading city, on main: pseudonymize
analyst-1 reading city, on the branch: unmasked
schema changes: 0
policy-tests: passed, findings 0, new 0, on main 0, waived 0, 24 tests and rows checked
enforcement-tests: passed, findings 0, new 0, on main 0, waived 0, 44 cases checked
removals: passed, findings 0, new 0, on main 0, waived 0, 87 columns checked
owner-review: failed, findings 1, new 1, on main 0, waived 0, 77 columns checked
owner-review/crm.learners.city: lowered from personal to internal; needs team-crm's approval
job: failed
owner-review, once team-crm approves: passed
owner-review, once team-analytics approves: failed
owner-review, two required, one from team-crm: failed
owner-review, two required, two from team-crm: passed
Una sola palabra en el archivo de metadatos desenmascara una columna para un rol completo, y ninguna comprobación salvo la regla del propietario lo detecta. analyst-1 lee city como pseudonymize en main, y como unmasked en la rama. El trabajo informa de 0 cambios de esquema, así que un verificador de cambios incompatibles no tiene nada que comparar. Las pruebas de políticas pasan, passed, findings 0, new 0, on main 0, waived 0, 24 tests and rows checked, y también las pruebas de aplicación, porque ninguna de ellas lee city, y la comprobación de eliminaciones pasa porque no se eliminó ninguna columna. Solo falla la regla del propietario, en lowered from personal to internal; needs team-crm's approval.
Lo que resuelve la regla del propietario es la aprobación del propietario. Las aprobaciones llegan a lib.ci.run como una entrada por cada revisión aprobatoria, con el nombre del equipo del revisor. Con la aprobación de team-crm, la regla del propietario informa passed, y con la de team-analytics, que no es propietario de la tabla, informa failed.
Regla práctica: Trata una clasificación bajada, un propietario cambiado y un traslado a otro dominio como cambios que necesitan la aprobación del propietario de la tabla en la rama principal, y haz fallar el trabajo hasta que se conceda; nunca confíes en un verificador de cambios incompatibles para ellos. Pide el motivo en la descripción de la columna en la misma solicitud de cambios. Una clasificación subida no necesita tal aprobación, porque solo puede ocultar más.
Deprecar una columna antes de eliminarla
La regla del propietario protege un cambio que los verificadores de cambios incompatibles no detectan. Eliminar una columna es el cambio que todos ellos sí detectan, pero para entonces la eliminación ya está en revisión, demasiado tarde para ayudar a los lectores a los que afecta. ODCS 3.2.0 añade una forma de advertir primero a los lectores. Cualquier elemento de un contrato, un objeto de esquema o una propiedad, incluidos los anidados, puede establecer el booleano opcional deprecated para indicar que ya no se recomienda su uso. El estándar también pide que la description apunte a un reemplazo y dé una guía de migración (esquema ODCS v3.2.0). Nuestra segunda regla convierte la advertencia de deprecación en un paso obligatorio: una columna solo puede salir de una tabla una vez que la rama principal la haya marcado como deprecada. Eso requiere dos pull requests, una que marca la columna como deprecada y otra que la elimina, y entre ambas los lectores de la columna tienen tiempo para dejar de usarla.
El archivo de metadatos de la plataforma no tenía ese campo, así que este capítulo lo añade: deprecated = true en la entrada de una columna. lib.metadata.load lo lee como Column.deprecated, que es false cuando está ausente, y lib.ci.contract lo escribe en el contrato de la columna como el deprecated de ODCS.
El mejor candidato de la plataforma es billing.payments.card_number. Su propia descripción dice que "no debería almacenarse en absoluto", y el capítulo 3 comprobó que guarda números de tarjeta completos. team-billing la elimina dos veces, cada una eliminando la columna en una migración y borrando su entrada de metadatos: una vez de inmediato, y otra después de que se haya fusionado una pull request que la depreca:
1"""team-billing removes the legacy card_number column from billing.payments: once straight away, and once after a pull2request that deprecates it has merged. The prose's point rests on the two removal lines."""3import yaml45from lib import ci67entry = ('8 = { name = "card_number", classification = "sensitive", '8 'description = "The full card number, from a legacy export. Should not be stored at all." }\n')9# the note goes after the description's sentence ending "at all.", and deprecated = true goes inside the entry's braces10deprecated_entry = entry.replace("all.", "all. Deprecated: reconcile payments by payment_id.").replace(" }", ", deprecated = true }")111213def remove_card_number(base, line):14 """A pull request on top of `base` that drops the column and deletes its metadata entry."""15 branch = ci.checkout(base)16 (branch / "migrations" / "0001-drop-card-number.sql").write_text("alter table billing.payments drop column card_number;\n")17 ci.edit(branch, "governance/metadata.toml", line, "")18 return branch192021main = ci.checkout()22deprecated = ci.checkout(main) # the first pull request: mark the column deprecated, and say what replaces it23ci.edit(deprecated, "governance/metadata.toml", entry, deprecated_entry)2425for base, line, name in ((main, entry, "straight away"), (deprecated, deprecated_entry, "after the deprecation merged")):26 report = ci.run(ci.build(base), ci.build(remove_card_number(base, line)), checks=["removals"])27 print(f"removal, {name}:", "passed" if report.checks[0].passed else "failed")28 for finding in report.checks[0].findings:29 print(f" {finding.id}:", finding.message)3031# property 7 is the eighth column, field 8: card_number, the column the deprecation marks32card_number = ci.contract(ci.build(deprecated), "billing.payments")["schema"][0]["properties"][7]33print("the deprecated column in its ODCS contract:")34print(yaml.safe_dump(card_number, sort_keys=False, width=200), end="")
python deprecate-then-remove.pyremoval, straight away: failed
removals/billing.payments.card_number: removed without being deprecated on the main branch first
removal, after the deprecation merged: passed
the deprecated column in its ODCS contract:
id: field-8
name: card_number
logicalType: string
physicalType: string
required: false
description: 'The full card number, from a legacy export. Should not be stored at all. Deprecated: reconcile payments by payment_id.'
classification: sensitive
deprecated: true
De inmediato, la eliminación falla, removed without being deprecated on the main branch first. Una vez fusionada la deprecación, la misma eliminación informa passed. Mientras tanto, el contrato llevó la advertencia a todos los que leen contratos, no solo al repositorio: deprecated: true, con una descripción que explica cómo conciliar los pagos sin la columna. La regla verifica el orden de los dos cambios, no el tiempo que hay entre ellos. El plazo que tienen los lectores es una decisión del equipo propietario y de los lectores de la columna, y el informe de impacto indica quiénes son esos lectores.
Regla práctica: Elimina una columna en dos pull requests: primero márcala como deprecada, con su reemplazo en la descripción, y fusiona ese cambio; después elimínala de la tabla y borra su entrada de los metadatos. Haz fallar cualquier eliminación de una columna que la rama principal no haya deprecado. Acuerda con los lectores de la columna cuánto durará la deprecación, ya que el trabajo solo comprueba que haya ocurrido primero.
Enruta las revisiones de cada dominio por ruta
La regla de propietarios pide que el equipo de una tabla apruebe sus degradaciones, y el repositorio puede enrutar esa solicitud. GitHub solicita automáticamente la revisión de los propietarios de código cuando una solicitud de cambios modifica código que ellos poseen, y una regla de protección de ramas puede exigir esa revisión (documentación de GitHub, About code owners). La plataforma guarda todos sus metadatos en un único archivo, governance/metadata.toml, lo que resulta adecuado para 5 equipos en un mismo repositorio. Sin embargo, un archivo tiene un solo conjunto de propietarios, de modo que la solicitud solo llega al equipo correcto si los metadatos de cada equipo viven bajo una ruta propia.
ODCS traza las mismas líneas. Un contrato indica un domain, el dominio lógico de datos al que pertenece (fundamentos de ODCS v3.2.0). ODCS no tiene un campo de propietario: la propiedad es un role de texto libre en un miembro del team del contrato (equipo de ODCS v3.2.0). lib.ci.contract escribe cada tabla descrita como un contrato ODCS. Registra el dominio, el equipo propietario como miembro con el rol owner, y cada columna como una propiedad cuyo id contiene su ID de campo de Iceberg. ODCS define el id de una propiedad como "Un identificador único del elemento utilizado para crear referencias estables y resistentes a refactorizaciones". lib.ci.generate escribe cada contrato en una carpeta de su dominio, y un archivo CODEOWNERS en .github/, el primer lugar donde GitHub lo busca. Ambos se generan a partir de los metadatos, nunca se escriben a mano. Pregúntate a quién solicitaría GitHub la degradación de city por parte del equipo de ciencia de datos:
1"""Ownership as ODCS contracts, a folder per domain, and who GitHub asks to review the downgrade of crm.learners.city2when the metadata is one shared file, and when each domain has a folder of contracts generated from it. The prose's3point rests on the first review line and on the contracts check failing before the files are generated again."""4import yaml56from lib import ci78main = ci.checkout() # the main branch holds the contracts and CODEOWNERS generated from its metadata9branch = ci.checkout(main)10ci.edit(branch, "governance/metadata.toml", '6 = { name = "city", classification = "personal"',11 '6 = { name = "city", classification = "internal"')1213shared = ["/governance/ @example-org/team-platform"] # one file for every domain, owned by the platform team14for path, owners in ci.reviewers(shared, ["governance/metadata.toml"]).items():15 print(f"one shared file, review of {path}:", " ".join(owners))1617crm = yaml.safe_load((main / "governance/contracts/crm/learners.odcs.yaml").read_text(encoding="utf-8"))18print(yaml.safe_dump({"domain": crm["domain"], "team": crm["team"]}, sort_keys=False), end="")19lines = (main / ".github/CODEOWNERS").read_text(encoding="utf-8").splitlines()20for line in lines[1:]: # the first line says the file is generated21 print("CODEOWNERS", line)22before, after = ci.build(main), ci.build(branch) # the pull request changes the metadata only23print("teams that own tables:", len({table.owner for table in before.described.values()}))24# drops the job's verdict, the last line, which this example doesn't print25for line in ci.lines(ci.run(before, after, checks=["contracts"]))[:-1]:26 print("before generating again,", line)27print("files generated again:", len(ci.generate(after)))28print("after generating again, contracts:", "passed" if ci.run(before, after, checks=["contracts"]).passed else "failed")29# the last matching CODEOWNERS line wins, as GitHub applies it30for path, owners in ci.reviewers(lines, ci.changed(main, branch)).items():31 print(f"a folder per domain, review of {path}:", " ".join(owners))
python domain-contracts.pyone shared file, review of governance/metadata.toml: @example-org/team-platform
domain: crm
team:
name: team-crm
members:
- username: team-crm
role: owner
CODEOWNERS /.github/CODEOWNERS @example-org/team-platform
CODEOWNERS /governance/ @example-org/team-platform
CODEOWNERS /migrations/ @example-org/team-platform
CODEOWNERS /pipelines/ @example-org/team-platform
CODEOWNERS /pipelines/course_performance.sql @example-org/team-analytics
CODEOWNERS /pipelines/learner_activity.sql @example-org/team-analytics
CODEOWNERS /governance/contracts/analytics/ @example-org/team-analytics
CODEOWNERS /governance/contracts/billing/ @example-org/team-billing
CODEOWNERS /governance/contracts/crm/ @example-org/team-crm
CODEOWNERS /governance/ci/domains/crm.rego @example-org/team-crm
CODEOWNERS /governance/contracts/learning/ @example-org/team-learning
CODEOWNERS /governance/contracts/support/ @example-org/team-support
teams that own tables: 5
before generating again, contracts: failed, findings 1, new 1, on main 0, waived 0, 11 files checked
before generating again, contracts/governance/contracts/crm/learners.odcs.yaml: differs from what the metadata generates: generate it again
files generated again: 11
after generating again, contracts: passed
a folder per domain, review of governance/contracts/crm/learners.odcs.yaml: @example-org/team-crm
a folder per domain, review of governance/metadata.toml: @example-org/team-platform
Con un único archivo compartido, la degradación cambia governance/metadata.toml, y GitHub solicita la revisión de @example-org/team-platform. Ese es el equipo que posee el archivo, no team-crm, al que pertenece la columna. El CODEOWNERS generado asigna al equipo de plataforma el propio archivo, porque About code owners indica que un repositorio está totalmente protegido contra cambios no autorizados solo cuando el propio archivo CODEOWNERS tiene un propietario (documentación de GitHub). El equipo de plataforma también se queda con los archivos de gobierno, las migraciones y los pipelines. Cada pipeline pasa entonces al equipo que posee su tabla, y cada carpeta de contratos al equipo de su dominio. La solicitud de cambios modificó solo los metadatos, así que la comprobación contracts, que vuelve a generar todos los archivos y compara, falla: differs from what the metadata generates: generate it again. Al generarlos de nuevo, la solicitud también cambia el contrato de crm, y su revisión va a @example-org/team-crm, porque GitHub da prioridad al último patrón coincidente. Un hook que genera los archivos ahorra al autor una ejecución fallida. La comprobación hace que el enrutamiento sea seguro.
Cuando se exige la revisión de los propietarios de código, basta la aprobación de cualquiera de los propietarios de un archivo (About code owners). La protección de ramas pide un único número de aprobaciones para toda la rama, cumplido por revisores con permisos de escritura (GitHub, ramas protegidas), de modo que cualquiera de esos revisores cuenta para él, y no puede pedir dos de los miembros de team-crm. El trabajo sí puede hacerlo, a partir de las aprobaciones que recibe. La regla de propietarios las cuenta por equipo, frente a un número por equipo en ci.toml. Con team-crm pidiendo dos, la degradación de city con una aprobación de team-crm informa failed, y con dos informa passed. La especificación del catálogo REST de Iceberg 1.12.0 ofrece otro lugar para las clasificaciones, labels por tabla e ID de campo (especificación del catálogo REST). La cobertura y las reglas de contrato podrían leer las etiquetas de un servidor de catálogo, pero los cambios en ellas necesitarían la revisión propia del servidor, ya que la especificación no exige que las etiquetas se persistan ni se versionen.
Regla práctica: Mantén los metadatos de cada dominio bajo una ruta propia, como un contrato ODCS por tabla con un dominio y un equipo propietario, generados a partir de los metadatos y comprobados por el trabajo, con una línea de CODEOWNERS para ese equipo. Asigna al equipo de plataforma el archivo CODEOWNERS, la configuración del trabajo, sus reglas globales, las exenciones y las migraciones. Exige la revisión de los propietarios de código, y cuenta las aprobaciones por equipo en el trabajo cuando una no basta.
Superponer las reglas de dominio sobre las reglas globales
Los equipos que son dueños de los contratos de sus dominios siguen compartiendo una sola plataforma, y algunas reglas deben cumplirse en todos los dominios. La descripción de Dehghani sobre la malla de datos llama a esto gobernanza computacional federada, "un conjunto de reglas globales, reglas aplicadas a todos los productos de datos y sus interfaces, para garantizar un ecosistema sano e interoperable". Esas reglas globales conviven con las decisiones que cada dominio toma por sí mismo, y la plataforma ejecuta ambas (Dehghani, 2020). Esto es un marco de referencia, no una medición, y se traduce en código. El equipo de plataforma mantiene un único paquete de reglas globales, sobre el que los dominios se ponen de acuerdo, y en la versión de Dehghani las decisiones las toman conjuntamente los propietarios de producto del dominio y de la plataforma. Cada dominio tiene un paquete propio, que es responsabilidad de su equipo, y un solo trabajo los ejecuta todos.
La herramienta del proyecto OPA para reglas sobre archivos es Conftest, que prueba datos de configuración estructurada con Rego (Conftest). lib.ci ejecuta el mismo tipo de reglas dentro del propio proceso con regopy, igual que el capítulo 5 ejecuta la política de acceso. governance/ci/global.rego contiene las reglas globales: un único propietario, sin importar si su rol va en mayúsculas o minúsculas; un dominio, que falla si el valor falta, está vacío o solo tiene espacios, ya que una cadena vacía es un valor definido en Rego y not por sí solo la daría por válida; una clasificación de las cuatro posibles, porque ODCS acepta cualquier cadena; y una descripción para cada columna. governance/ci/domains/crm.rego contiene la regla de team-crm: nada en crm es público, porque todo lo que contiene describe a un alumno o a un instructor. La comprobación contract-rules ejecuta el paquete global sobre todos los contratos, y el paquete de cada dominio sobre los contratos de ese dominio en la rama. Una regla devuelve cada infracción como datos, con el nombre de la regla, un sujeto y un mensaje. El sujeto de una infracción y el nombre de la regla forman el ID del hallazgo. Estos archivos están fuera de governance/policies/, la carpeta de la política de acceso, de modo que cambiarlos nunca altera la revisión de la política que el capítulo 8 registra con cada decisión.
El cambio del equipo de CRM vuelve, esta vez con metadatos. work_email se clasifica como public, con el argumento de que una dirección de trabajo es información empresarial, y su descripción está vacía. El segundo intento añade una descripción y traslada crm.learners al dominio de analítica, que no tiene reglas propias:
1"""The platform's global rules and the crm domain's own rule, run on the CRM team's two tries at work_email: classified2public with no description, then described with crm.learners moved to the analytics domain, which has no rules of its own.3The prose's point rests on the two contract-rules findings of the first try and on the owner-review finding after the move."""4from lib import ci56main = ci.checkout()7branch = ci.checkout(main)8(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")9ci.edit(branch, "governance/metadata.toml", '15 = { name = "notes"',10 '16 = { name = "work_email", classification = "public", description = "" }\n15 = { name = "notes"')1112for path in sorted((branch / "governance" / "ci").rglob("*.rego")):13 print("rules:", path.relative_to(branch).as_posix())14before = ci.build(main)15report = ci.run(before, branch, checks=["coverage", "contract-rules"])16for line in ci.lines(report):17 print(line)1819# The second try: a description, and the table moved to a domain whose rules allow public columns.20ci.edit(branch, "governance/metadata.toml", 'description = "" }', 'description = "The learner\'s work address." }')21# the table's domain changes from crm to analytics, which has no rules of its own22ci.edit(branch, "governance/metadata.toml", 'owner = "team-crm"\ndomain = "crm"\ndescription = "Every learner',23 'owner = "team-crm"\ndomain = "analytics"\ndescription = "Every learner')24report = ci.run(before, branch, checks=["coverage", "contract-rules", "owner-review"])25for line in ci.lines(report):26 print("moved to analytics,", line)
python global-and-domain-rules.pyrules: governance/ci/domains/crm.rego
rules: governance/ci/global.rego
coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
contract-rules: failed, findings 2, new 2, on main 0, waived 0, 10 contracts checked
coverage/ai.review_corpus: no metadata; on main, owner team-platform
coverage/crm.learners.work_email: classified public; its name suggests personal; needs team-crm's approval
coverage/marketing.audience: no metadata; on main, owner team-platform
contract-rules/crm.learners.work_email/described: no description (global rule described)
contract-rules/crm.learners.work_email/no-public: crm classifies no column public (domains.crm rule no-public)
change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
job: failed
moved to analytics, coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
moved to analytics, contract-rules: passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked
moved to analytics, owner-review: failed, findings 1, new 1, on main 0, waived 0, 77 columns checked
moved to analytics, coverage/ai.review_corpus: no metadata; on main, owner team-platform
moved to analytics, coverage/crm.learners.work_email: classified public; its name suggests personal; needs team-crm's approval
moved to analytics, coverage/marketing.audience: no metadata; on main, owner team-platform
moved to analytics, owner-review/crm.learners/domain: domain changed from crm to analytics; needs team-crm's approval
moved to analytics, change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
moved to analytics, job: failed
La cobertura marca ahora la clasificación: classified public; its name suggests personal; needs team-crm's approval. Un nombre es una evidencia, y un pull request no tiene valores que leer, así que una clasificación inferior a la que sugiere el nombre es un hallazgo que solo el propietario en la rama principal puede responder.
Las reglas de contrato exigen más. El paquete global marca no description (global rule described), y el paquete de crm marca crm classifies no column public (domains.crm rule no-public). team-crm tomó la segunda decisión sin consultar a ningún otro equipo, y la plataforma la aplica por ellos en cada solicitud de cambios, incluidas las solicitudes de team-crm.
En el segundo intento se aplican las reglas del dominio de analítica, y las reglas de contrato pasan: passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked. El traslado en sí falla, en domain changed from crm to analytics; needs team-crm's approval, y también falla la clasificación.
Regla práctica: Escribe las reglas que todo dominio debe cumplir como un único paquete global, mantenido por el equipo de plataforma, y deja que cada dominio añada un paquete propio, cuyo responsable sea su equipo, que se ejecute solo sobre los contratos de ese dominio. Devuelve las infracciones como datos, con un sujeto estable, nunca como un simple aprobado o suspendido. Haz que las reglas de dominio se sumen a las globales, nunca que las reemplacen, y trata el traslado de una tabla a otro dominio como un cambio de propiedad, para que ningún equipo escape a las reglas de su dominio cambiando una sola palabra.
Contar los hallazgos exceptuados por verificación
Las verificaciones vistas hasta ahora hacen fallar cada pull request por una razón. Una puerta de control también falla cuando la gente deja de creer en ella. Los autores de Tricorder, de Google, definen como falso positivo efectivo cualquier informe que un usuario decide no atender, y mantienen esa tasa por debajo del 10 % en la revisión de código. Lo que sí miden es algo más acotado, la tasa de no útil: los clics de Not useful como proporción de los clics de Not useful, Please fix y Apply fix de un analizador. Con un 10 % o más, el analizador pasa a periodo de prueba, y por encima del 25 % puede desactivarse de inmediato (Sadowski et al., 2015). Se trata del análisis de código de una empresa, con umbrales que ella misma eligió, y no conocemos un equivalente publicado para el gobierno de datos. La medida se traslada como analogía. Cuenta, para cada verificación, los hallazgos que nadie atiende, ya sea con excepción o dejados en main.
En la plataforma, la decisión de no atender un hallazgo nuevo es una excepción. Una excepción en governance/waivers.toml nombra un hallazgo por su ID, el equipo responsable de él, un motivo y el último día en que aplica. lib.ci acepta una excepción que se extiende como máximo 90 días después del día en que se ejecuta el trabajo. Ese límite es una regla práctica recogida en governance/ci.toml, de modo que cada excepción vuelva a someterse a una decisión. El mismo archivo enumera las verificaciones que ninguna excepción puede silenciar, sea cual sea su fecha: la cobertura, ya que una tabla sin propietario o una columna sin clasificación se corrige en el propio pull request, y las pruebas de aplicación obligatoria. Un hallazgo que ya está en main no necesita excepción. Una excepción vencida no silencia nada, y el informe la enumera. El equipo de la plataforma es dueño del archivo de excepciones, así que cada excepción también es un cambio revisado.
El cambio del CRM necesita dos excepciones. La primera cubre la columna sin clasificar. La segunda cubre, una vez clasificada la columna personal, la descripción que todavía no se ha escrito. El equipo pide primero que la segunda dure hasta el verano, y luego hasta el 31 de octubre:
1"""Waivers on the CRM team's pull request: one for the unclassified work_email column, which coverage never allows;2then, with the column classified but not yet described, one that asks for too long, and one that fits, on the book's3today and a month later. The prose's point rests on the two refusals and on the expired waiver the report lists."""4from datetime import date56from lib import ci7from lib.platform import TODAY8910def waive(branch, finding, expires, reason):11 with open(branch / "governance" / "waivers.toml", "a", encoding="utf-8") as waivers:12 # the date is written unquoted, so TOML reads it as a date, which the job compares with the day it runs13 waivers.write(f'\n[[waivers]]\nfinding = "{finding}"\nowner = "team-crm"\nreason = "{reason}"\nexpires = {expires}\n')141516main = ci.checkout()17before = ci.build(main)18unclassified = ci.checkout(main)19(unclassified / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")20waive(unclassified, "coverage/crm.learners.work_email", "2026-10-31", "Classified once the sign-up form is live.")21for line in ci.lines(ci.run(before, unclassified, checks=["coverage"])):22 print("unclassified,", line)2324undescribed = ci.checkout(main) # the second try: classified, with its description still to come25(undescribed / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")26ci.edit(undescribed, "governance/metadata.toml", '15 = { name = "notes"',27 '16 = { name = "work_email", classification = "personal", description = "" }\n15 = { name = "notes"')28waive(undescribed, "contract-rules/crm.learners.work_email/described", "2027-06-30", "Described once the form's copy is final.")29after = ci.build(undescribed)30for line in ci.lines(ci.run(before, after, checks=["coverage", "contract-rules"])):31 print("undescribed, asked until 2027-06-30,", line)3233# the same waiver, shortened to the end of October, within the longest a waiver may run34ci.edit(undescribed, "governance/waivers.toml", "2027-06-30", "2026-10-31")35for day in (TODAY, date(2026, 11, 1)): # the book's today, then a month later, after the waiver has expired36 report = ci.run(before, after, today=day, checks=["coverage", "contract-rules"])37 print(f"undescribed, asked until 2026-10-31, on {day}, contract-rules:", "passed" if report.checks[1].passed else "failed")38 print(f"undescribed, asked until 2026-10-31, on {day}, findings waived:", sum(len(c.waived) for c in report.checks))39 print(f"undescribed, asked until 2026-10-31, on {day}, waivers that silence nothing:",40 "; ".join(why for _, why in report.unused) or "none")
python waived-findings.pyunclassified, coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
unclassified, coverage/ai.review_corpus: no metadata; on main, owner team-platform
unclassified, coverage/crm.learners.work_email: not classified; its name suggests personal
unclassified, coverage/marketing.audience: no metadata; on main, owner team-platform
unclassified, change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
unclassified, waiver coverage/crm.learners.work_email: silences nothing, coverage findings are never waived
unclassified, job: failed
undescribed, asked until 2027-06-30, coverage: passed, findings 2, new 0, on main 2, waived 0, 12 tables checked
undescribed, asked until 2027-06-30, contract-rules: failed, findings 1, new 1, on main 0, waived 0, 10 contracts checked
undescribed, asked until 2027-06-30, coverage/ai.review_corpus: no metadata; on main, owner team-platform
undescribed, asked until 2027-06-30, coverage/marketing.audience: no metadata; on main, owner team-platform
undescribed, asked until 2027-06-30, contract-rules/crm.learners.work_email/described: no description (global rule described)
undescribed, asked until 2027-06-30, change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
undescribed, asked until 2027-06-30, waiver contract-rules/crm.learners.work_email/described: silences nothing, runs to 2027-06-30, past the longest allowed, 2026-12-30
undescribed, asked until 2027-06-30, job: failed
undescribed, asked until 2026-10-31, on 2026-10-01, contract-rules: passed
undescribed, asked until 2026-10-31, on 2026-10-01, findings waived: 1
undescribed, asked until 2026-10-31, on 2026-10-01, waivers that silence nothing: none
undescribed, asked until 2026-10-31, on 2026-11-01, contract-rules: failed
undescribed, asked until 2026-10-31, on 2026-11-01, findings waived: 0
undescribed, asked until 2026-10-31, on 2026-11-01, waivers that silence nothing: expired on 2026-10-31
La excepción para la columna sin clasificar se rechaza, aunque pide solo un mes: silences nothing, coverage findings are never waived. Ninguna excepción puede hacer pasar ese pull request. La excepción para la descripción se rechaza mientras dura hasta el verano, silences nothing, runs to 2027-06-30, past the longest allowed, 2026-12-30. Acortada al 31 de octubre, silencia el hallazgo. El 1 de octubre, las reglas de contrato informan passed. El 1 de noviembre informan failed. El 1 de octubre, la lista de excepciones que no silencian nada es none; el 1 de noviembre es expired on 2026-10-31: pasó la fecha, pero el problema no.
Regla práctica: haz que una excepción nombre exactamente un hallazgo que introduce un pull request (es decir, uno solo), con un equipo responsable, un motivo y una fecha de fin a no más de unos pocos meses, y enumera las verificaciones que ninguna excepción puede silenciar, como una clasificación o un propietario que falte. Informa, para cada verificación, cuántos hallazgos nadie atendió, ya sea con excepción o dejados en main, y revisa cualquier verificación en la que eso sea la mayoría: o la verificación está mal, o lo está la plataforma; el recuento oculta cuál de las dos.
Qué sale mal en producción
A nuestro juicio, un trabajo de gobernanza se desactiva más a menudo de lo que se rompe: los equipos eliminan las comprobaciones que son lentas o ruidosas, una línea de governance/ci.toml a la vez, y la puerta de control sigue aprobando mientras protege menos. Dos comprobaciones por etapas muestran cómo ocurre, con recuentos en lugar de tiempos, y una tercera muestra un trabajo que se rompe.
Una comprobación que lee cada fila
El equipo de soporte añade dos columnas a support.tickets: callback_number, clasificada como internal, y reply_email, clasificada como public. Un equipo que quiera juzgar los valores, y no solo los nombres, añade entonces al trabajo la clasificación de la tabla que aparece en el capítulo 3, tanto por muestra como por cada fila:
1"""The support team's pull request adds two columns to support.tickets, which coverage judges by their names and chapter23's value checks judge by reading a sample, or every row. The prose's point rests on the callback number's empty column3and on the values each check reads; counts of values stand in for time, which depends on the machine."""4import pyarrow as pa56from lib import ci, pii78main = ci.checkout()9branch = ci.checkout(main)10(branch / "migrations" / "0001-callback-and-reply.sql").write_text(11 "alter table support.tickets add column callback_number varchar;\n"12 "alter table support.tickets add column reply_email varchar;\n")13ci.edit(branch, "governance/metadata.toml", '8 = { name = "status"',14 '9 = { name = "callback_number", classification = "internal", description = "A number to call the learner back on." }\n'15 '10 = { name = "reply_email", classification = "public", description = "Where the reply goes." }\n8 = { name = "status"')16before, after = ci.build(main), ci.build(branch)1718report = ci.run(before, after, checks=["coverage", "classify-sampled", "classify-every-row"])19for name in ("body", "callback_number", "reply_email"):20 values = after.catalog.load_table("support.tickets").scan(selected_fields=(name,)).to_arrow()[name]21 print(f"support.tickets.{name}, values on the branch:", f"{len(values) - values.null_count:,}")22 for check in report.checks:23 found = [f.message for f in check.findings if f.id == f"{check.name}/support.tickets.{name}"]24 print(f"support.tickets.{name}, {check.name}:", found[0] if found else "no finding")25for check in report.checks[1:]:26 print(f"{check.name}, values read:", f"{check.checked:,}")2728text_columns, sampled, every_row = 0, 0, 029for name in sorted(before.described):30 data = before.catalog.load_table(name).scan().to_arrow()31 # the non-null values of each text column, the ones a value check classifies32 filled = [len(column) - column.null_count for column in data.columns if pa.types.is_string(column.type)]33 text_columns += len(filled)34 # the sampled check reads at most pii.ROWS values of each column35 sampled += sum(min(pii.ROWS, count) for count in filled)36 every_row += sum(filled)37print("text columns in the described tables:", text_columns)38print("values the sampled check would read in them:", f"{sampled:,}")39print("values the every-row check would read in them:", f"{every_row:,}")
python slow-check-every-row.pysupport.tickets.body, values on the branch: 2,000
support.tickets.body, coverage: no finding
support.tickets.body, classify-sampled: values support sensitive, reviewed as personal
support.tickets.body, classify-every-row: values support sensitive, reviewed as personal
support.tickets.callback_number, values on the branch: 0
support.tickets.callback_number, coverage: no finding
support.tickets.callback_number, classify-sampled: no finding
support.tickets.callback_number, classify-every-row: no finding
support.tickets.reply_email, values on the branch: 0
support.tickets.reply_email, coverage: classified public; its name suggests personal; needs team-support's approval
support.tickets.reply_email, classify-sampled: its name suggests personal, reviewed as public
support.tickets.reply_email, classify-every-row: its name suggests personal, reviewed as public
classify-sampled, values read: 1,000
classify-every-row, values read: 10,000
text columns in the described tables: 32
values the sampled check would read in them: 5,800
values the every-row check would read in them: 429,453
La cobertura falla reply_email por su nombre, classified public; its name suggests personal; needs team-support's approval, y pasa callback_number, no finding, porque ninguna regla de nombres coincide con ella. La rama contiene 0 valores en la nueva columna, así que leer valores tampoco ayuda todavía. La migración añade la columna vacía, y cada fila da no finding. La muestra programada del capítulo 3 detecta los números de teléfono una vez que la columna se llena.
La comprobación por muestra lee 1,000 valores y la comprobación de cada fila lee 10,000. Ambas encuentran support.tickets.body sensible bajo una clasificación personal, que el capítulo 3 ya envió a team-support. En todas las columnas de texto de las tablas descritas, una muestra leería 5,800 valores, y cada fila leería 429,453. El segundo número crece con los datos, en cada solicitud de cambios, sea cual sea el cambio que incluya. Un trabajo que hace esperar a la gente, a nuestro juicio, acaba omitiéndose y después eliminándose.
Regla práctica: Dimensiona las comprobaciones de las solicitudes de cambios según el cambio, no según los datos: metadatos, esquemas, políticas y los nombres de las columnas que una solicitud añade. Ejecuta las comprobaciones que leen valores según una programación, con una muestra fija, como hace el capítulo 3, y envía sus resultados al equipo responsable. Documenta dónde se detienen las comprobaciones del trabajo, por ejemplo en una columna añadida vacía.
Una verificación que marca cada ID
Un equipo prudente añade una verificación que trata cada columna con nombre de ID como dato personal. La plataforma decidió otra cosa para los IDs que utiliza en sus uniones: capítulo 2 clasifica learner_id como internal y protege la tabla que lo resuelve. Los hallazgos de la verificación son nuevos, así que cada equipo propietario los exceptúa:
1"""A noisy check added to the job: every column named like an ID is personal. The platform decided otherwise for IDs2used for joining, so each owning team waives its findings, and the waiver count climbs. The prose's point rests on the3not-acted-on line of each check."""4from collections import Counter56from lib import ci78main = ci.checkout()9branch = ci.checkout(main) # the platform team adds the check to the job's settings10ci.edit(branch, "governance/ci.toml", '"properties"]', '"properties", "id-columns"]')11before, after = ci.build(main), ci.build(branch)1213report = ci.run(before, after)14print("waivers in the file, before:", len(ci.waivers(after.governance)))15noisy = next(check for check in report.checks if check.name == "id-columns")16print("job, before the waivers:", "passed" if report.passed else "failed")17print("id-columns, findings:", len(noisy.findings))18print("id-columns, findings on main:", len(noisy.on_main))19# the last word of each message is the classification20classified = Counter(finding.message.rpartition(" ")[2] for finding in noisy.findings)21for level, count in sorted(classified.items()):22 print(f"id-columns, findings classified {level}:", count)23# the part of the finding's ID after the check's name: the column's full name24print("id-columns, the public one:", ", ".join(f.id.split("/")[1] for f in noisy.findings if f.message.endswith("public")))2526with open(after.governance / "waivers.toml", "a", encoding="utf-8") as waivers:27 for finding in noisy.findings:28 waivers.write(f'\n[[waivers]]\nfinding = "{finding.id}"\nowner = "{finding.owner}"\n'29 'reason = "An ID for joining, internal by decision."\nexpires = 2026-10-31\n')3031report = ci.run(before, after)32print("waivers in the file, after:", len(ci.waivers(after.governance)))33print("job, with the waivers:", "passed" if report.passed else "failed")34for check in (check for check in report.checks if check.findings):35 idle = [f for f in check.findings if f.waiver or f.on_main] # findings nobody acted on36 print(f"{check.name}, not acted on:", f"{len(idle)} of {len(check.findings)} findings, {len(idle) / len(check.findings):.0%}: "37 f"{len(check.waived)} waived, {len(check.on_main)} on main")
python noisy-check-waivers.pywaivers in the file, before: 0
job, before the waivers: failed
id-columns, findings: 21
id-columns, findings on main: 0
id-columns, findings classified internal: 20
id-columns, findings classified public: 1
id-columns, the public one: learning.courses.course_id
waivers in the file, after: 21
job, with the waivers: passed
coverage, not acted on: 2 of 2 findings, 100%: 0 waived, 2 on main
properties, not acted on: 4 of 4 findings, 100%: 0 waived, 4 on main
id-columns, not acted on: 21 of 21 findings, 100%: 21 waived, 0 on main
La verificación encuentra 21 columnas, cada una un ID que la plataforma clasificó a propósito. 20 de ellas son internal, y learning.courses.course_id es public.
El archivo de excepciones pasa de 0 excepciones a 21, y la verificación de IDs muestra 21 of 21 findings, 100%: 21 waived, 0 on main. Eso supera cualquier umbral que los autores de Tricorder utilizan, solo como analogía, ya que los suyos cuentan clics y no excepciones. La verificación de propiedades muestra la misma proporción, 4 of 4 findings, 100%: 0 waived, 4 on main, y es correcto que así sea: sus hallazgos son una corrección que necesita el ejecutor del pipeline. El recuento no permite distinguir ambos casos, pero las razones sí.
Regla práctica: Antes de añadir una verificación, ejecútala en la rama principal y lee cada hallazgo; si la mayoría se exceptuaría, cambia la regla en lugar de exceptuar sus hallazgos. Elimina una verificación cuyos hallazgos sigan exceptuándose en su mayoría, y trata una proporción alta en una verificación correcta como trabajo que hay que programar, con un responsable y una fecha.
Un archivo roto se convierte en un hallazgo
La entrada de un agente de soporte se añade a governance/users.toml con una comilla faltante. La misma solicitud de cambios modifica crm.learners.country de texto a número, y además incluye el work_email sin clasificar del equipo de CRM:
1"""A pull request that breaks two files the job reads: a support agent added to the users file with a quote missing,2and a migration Iceberg refuses. It also carries the CRM team's unclassified work_email column. The prose's point rests3on the two checks that could not run and on the exit code."""4from lib import ci56main = ci.checkout()7branch = ci.checkout(main)8# the closing quote after "support" is missing, so the users file no longer parses9ci.edit(branch, "governance/users.toml", '[users.agent-a09]', '[users.agent-a12]\ngroups = ["support]\nregion = "emea"\n\n'10 '[users.agent-a09]')11(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")12# a string column cannot become an int: that isn't one of Iceberg's type promotions, so the migration is refused13(branch / "migrations" / "0002-country-as-number.sql").write_text("alter table crm.learners alter column country type int;\n")14print("files the pull request changes:", ", ".join(ci.changed(main, branch)))1516report = ci.run(main, branch)17for line in ci.lines(report):18 print(line)19print("checks that could not run:", ", ".join(check.name for check in report.checks if check.error))20print("checks that ran:", sum(check.error is None for check in report.checks))21print("exit code:", report.exit_code)
python broken-files-become-findings.pyfiles the pull request changes: governance/users.toml, migrations/0001-add-work-email.sql, migrations/0002-country-as-number.sql
coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
contract-rules: passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked
contracts: passed, findings 0, new 0, on main 0, waived 0, 11 files checked
policy-tests: failed, the check could not run
enforcement-tests: failed, the check could not run
migrations: failed, findings 1, new 1, on main 0, waived 0, 2 migrations checked
pipelines: passed, findings 0, new 0, on main 0, waived 0, 4 pipelines checked
lineage-classifications: passed, findings 0, new 0, on main 0, waived 0, 23 columns checked
owner-review: passed, findings 0, new 0, on main 0, waived 0, 77 columns checked
removals: passed, findings 0, new 0, on main 0, waived 0, 87 columns checked
properties: passed, findings 4, new 0, on main 4, waived 0, 12 tables checked
coverage/ai.review_corpus: no metadata; on main, owner team-platform
coverage/crm.learners.work_email: not classified; its name suggests personal
coverage/marketing.audience: no metadata; on main, owner team-platform
policy-tests/error: the check could not run: governance/users.toml doesn't parse: Illegal character '\n' (at line 13, column 20)
enforcement-tests/error: the check could not run: governance/users.toml doesn't parse: Illegal character '\n' (at line 13, column 20)
migrations/0002-country-as-number.sql: refused: Cannot change column type: country: string -> int
properties/ai.review_corpus: 7 of 7 generated properties missing; on main, owner team-platform
properties/analytics.course_performance: 4 of 4 generated properties missing; on main, owner team-analytics
properties/analytics.learner_activity: 4 of 4 generated properties missing; on main, owner team-analytics
properties/marketing.audience: 7 of 7 generated properties missing; on main, owner team-platform
change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
job: failed
checks that could not run: policy-tests, enforcement-tests
checks that ran: 9
exit code: 1
El archivo de usuarios hace fallar las dos comprobaciones que lo leen: the check could not run: governance/users.toml doesn't parse: Illegal character '\n' (at line 13, column 20). Iceberg rechaza el cambio de tipo, que no es una promoción, como refused: Cannot change column type: country: string -> int. Las dos comprobaciones que no pudieron ejecutarse no detienen las demás comprobaciones, entre ellas las migraciones, así que el autor también ve not classified; its name suggests personal, y el trabajo termina con el código de salida 1. Sin la captura, el trabajo se detendría en el primer error, y el autor tendría que corregir un problema por ejecución.
Regla práctica: Convierte una comprobación que se bloquea en un único hallazgo que hace fallar el trabajo, con la primera línea del error y el archivo que menciona, ejecuta de todos modos las demás comprobaciones y nunca permitas que una exención lo silencie.
Otros fallos
- Un control que nadie exigió. Un trabajo cuya verificación de estado no exige la protección de la rama informa de sus hallazgos, y la solicitud de cambios se fusiona de todos modos. Exígela y cuenta las solicitudes de cambios fusionadas cuyo trabajo falló.
- Una compilación rota oculta hallazgos. Una tabla que una canalización rota no escribió no puede detectarse como una tabla sin describir. Revisa primero la verificación
pipelines. - Las exenciones sobreviven a su motivo. Un hallazgo se corrige y su exención permanece, lista para ocultar el siguiente con el mismo ID. El informe enumera las exenciones que no coinciden con ningún hallazgo; elimínalas.
- Un cambio de nombre altera los ID de los hallazgos. Los ID nombran columnas, así que los hallazgos de una columna renombrada vuelven con ID nuevos, y el informe enumera sus exenciones como si no coincidieran con ningún hallazgo. Traslada las exenciones en la solicitud de cambios del renombrado.
- Una aprobación sobrevive a lo que aprobó.
team-crmaprueba la degradación decity, luego el autor sube una degradación deemail, y la aprobación cubre ambas. Activa en la protección de la rama la opción «descartar las aprobaciones de solicitudes de cambios obsoletas cuando se suban commits que afecten a las diferencias de la solicitud de cambios». - Una sola aprobación representa a un equipo. La aprobación de cualquier propietario de código cumple el requisito de GitHub, y el recuento de la protección de la rama es por rama. Cuenta las aprobaciones por equipo en el trabajo donde un dominio requiere más.
- El equipo bloqueado edita el control. Un equipo cuya solicitud de cambios falla elimina la verificación de
ci.toml, añade una exención o edita CODEOWNERS. Asigna a los tres como propietario de código al equipo de plataforma. - Cambios fuera de las solicitudes de cambios. Un cuaderno crea una tabla, o una migración se ejecuta a mano. Ejecuta también el trabajo contra producción de forma programada, como lo hace el capítulo 2 con
problems.
Lo que decidió este capítulo
- Un solo trabajo ejecuta las comprobaciones de los capítulos 2 a 7 en cada pull request,
lib.ci.run, listadas engovernance/ci.toml; solo la muestra de valores del capítulo 3 se ejecuta, en cambio, de forma programada.lib.ci.maindevuelve el código de salida y escribe el informe en Markdown. - El trabajo juzga lo que cambia el pull request. Un hallazgo que este introduce hace fallar el trabajo, salvo que se apruebe o se exima; un hallazgo que ya está en main se informa con su propietario y no hace fallar nada. Una comprobación que falla por un error cuenta como un hallazgo que hace fallar el trabajo.
- Cada hallazgo tiene un ID estable, formado por la comprobación y su sujeto, como
coverage/crm.learners.work_email. - Un pull request se compara con la rama main en plataformas de prueba construidas igual que la plataforma las ejecuta, cada una con sus propias migraciones y pipelines.
- Los cambios de esquema se comparan por ID de campo y se informan de tres maneras: los lectores de Iceberg, los pipelines cuyo SQL nombra la columna y cada columna a la que el linaje dice que llega, incluidas las aristas INDIRECT.
- Dos reglas propias: rebajar una clasificación, cambiar un propietario o mover una tabla a otro dominio requiere la aprobación del propietario de la tabla en la rama main, contada por equipo; y una columna solo se elimina después de que la rama main la haya marcado como
deprecated. - La propiedad es un contrato ODCS por tabla, con un dominio y el equipo propietario en el rol
owner, generado en una carpeta por dominio con una línea de CODEOWNERS, y comprobado por el trabajo. El equipo de plataforma es propietario de CODEOWNERS, de la configuración del trabajo, de sus reglas globales, de las exenciones y de las migraciones. - Las reglas globales y las reglas de dominio están escritas en Rego, se ejecutan dentro del proceso con regopy en cada contrato, fuera de la carpeta de la política de acceso.
- Las brechas sembradas a propósito se mantienen en main:
marketing.audienceyai.review_corpusaparecen en cada informe como hallazgos de cobertura, con el equipo de plataforma como propietario, hasta que se describan. - El ruido se mide como hallazgos a los que nadie responde, por comprobación: eximidos, o dejados en main. Una comprobación cuyos hallazgos se ignoran en su mayoría es incorrecta o lo es la plataforma, y el recuento por sí solo no permite saber cuál. Una exención nombra un solo hallazgo, un propietario, un motivo y una fecha de fin a no más de 90 días; la cobertura y las pruebas de aplicación de las reglas nunca se eximen.
- Las comprobaciones de los pull requests se dimensionan según el cambio; las comprobaciones que leen valores se ejecutan de forma programada. Las comprobaciones solo son útiles mientras la gente las mantiene activas, así que cada una está dimensionada al cambio.
Este capítulo, en esta edición
Edición 2026.11.31Ejemplos verificados el 19 de nov de 2026Superan la prueba 10 de 10 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.31.