Política de Documentación de MxOS

Fronteras de Contenido, Gobernanza Editorial y Modelo de Fuentes

Autores:
Organización:

Fundación MxOS, A.C.

Fecha:

Septiembre 2026

Estado:

Estándar Activo

Propósito y Principios de la Política

El objetivo fundamental de esta política es delimitar con absoluta precisión la frontera de responsabilidades entre el Portal Central de Documentación (el agregador oficial en docs.mx-os.mx) y la documentación interna de cada repositorio (in-repo documentation).

Para evitar cuellos de botella de mantenimiento, duplicaciones de contenido y desincronizaciones de versiones, la documentación de la Fundación MxOS se rige por tres principios innegociables:

  1. Fuente Única de Verdad (Single Source of Truth): Ningún procedimiento operativo o detalle de implementación debe escribirse dos veces. Cada dato técnico reside exclusivamente en su repositorio de origen.

  2. El Portal es la Puerta de Entrada (Entry Point): El portal general ofrece la vista panorámica, los fundamentos filosóficos/metodológicos y la guía de replicación de alto nivel que articula todo el ecosistema.

  3. Mantenimiento Autónomo In-Repo: Cada repositorio o proyecto del ecosistema mantiene su propia documentación de desarrollo y operación, con total autonomía de ciclo de vida.

Frontera de Contenidos: Portal Central vs. Documentación In-Repo

Dimensión

Portal Central (docs/portal -> docs.mx-os.mx)

Repositorios del Ecosistema (In-Repo)

Audiencia Principal

Nuevos colaboradores, directores técnicos, auditores, replicadores del sistema operativo y público general.

Desarrolladores activos, mantenedores de paquetes, operadores de infraestructura y constructores de imágenes.

Alcance y Enfoque

Alto nivel: Misión, gobernanza, marco legal, metodología de replicación transversal y guías de incorporación.

Bajo nivel: Arquitectura interna del componente, opciones de configuración CLI, variables de entorno, pruebas y APIs.

Contenido Obligatorio

  • Misión, visión y estatutos de la Asociación Civil.

  • Guía de Replicación Maestra (visión holística de las 4 etapas del pipeline).

  • Estándares transversales de contribución y estilo (RST, políticas de documentación).

  • Mapa de proyectos y directorio de repositorios soberanos.

  • README.rst estándar con instrucciones de clonación, compilación y pruebas.

  • Directorio docs/ con especificaciones detalladas del componente.

  • Archivos de configuración comentados e instrumentados.

  • Manuales técnicos de uso de scripts o herramientas específicas.

Contenido Prohibido

  • Procedimientos paso a paso de micro-herramientas internas.

  • Fragmentos de código fuente o playbooks duplicados de otros repositorios.

  • Flags de comandos o detalles de implementación sujetos a cambio frecuente en repos individuales.

  • Estatutos institucionales o acuerdos organizacionales generales.

  • Duplicación de las guías de estilo globales de la Fundación.

Distribución de Responsabilidades por Repositorio

A continuación se detalla qué tipo de documentación corresponde a cada repositorio y proyecto activo de la Fundación:

Repositorio Central de Documentación (docs/portal)

  • Rol: Agregador Sphinx que compila el sitio web oficial docs.mx-os.mx.

  • Contenido: - Índices principales (toctree) y navegación del portal. - Submódulos Git de documentación modular (organización, administración, legales, empaquetamiento, operaciones, replicación, guías). - Guía maestra de replicación de alto nivel: explicación holística de cómo se ensambla MxOS a partir de CentOS Stream 10. - Enlaces directos a los repositorios de desarrollo en la forja soberana (git.mx-os.mx).

Sincronización y Empaquetamiento (rpms-sync)

  • Rol: Ingesta de fuentes desde upstream (GitLab dist-git y Koji Stream), espejado del lookaside cache y mantenimiento de ramas.

  • Contenido In-Repo: - FLUJO.rst: Protocolo detallado de sincronización de ramas, resolución de conflictos durante el rebase y reglas de inmutabilidad de c10s. - Manual de operación de scripts CLI de sincronización y descarga de fuentes de sources.mx-os.mx. - Manejo de side tags y composes de Koji a nivel de automatización de ingesta.

Granja de Compilación Koji (ansible-koji)

  • Rol: Automatización con Ansible del cluster de compilación Koji Hub, Mock builders, base de datos PostgreSQL y firma de paquetes Siguldry.

  • Contenido In-Repo: - Arquitectura detallada de red y certificados SSL/TLS para el Hub y los constructores. - Procedimientos de inicialización de base de datos, creación de usuarios y certificados de cliente. - Configuración de tags de Koji (c10s-build, c10s-candidate, side tags) y políticas de compilación. - Guía de administración, respaldos y monitoreo del servicio Koji.

Generación de Medios e Imágenes (iso/mxos-mkosi e iso/mxos-kiwi)

  • Rol: Construcción determinista y declarativa de imágenes de estación de trabajo en paridad funcional 1:1.

  • Contenido In-Repo: - README.rst en cada directorio explicando el motor utilizado (mkosi vs. kiwi-ng). - Parámetros de particionado GPT, subvolúmenes Btrfs y configuración de Unified Kernel Images (UKI) con systemd-boot. - Procedimiento de ejecución local mediante make o run.bash, pruebas en máquinas virtuales con QEMU/KVM y depuración. - Documentación de paridad de características entre ambas herramientas.

Estructura Estándar para Repositorios del Ecosistema

Todo repositorio creado bajo la organización de la Fundación MxOS debe incluir una estructura mínima de documentación en su raíz:

  1. `README.rst`: - Título formal y descripción sintética del proyecto. - Requisitos previos y dependencias de sistema. - Instrucciones directas de compilación, ejecución o despliegue. - Guía de pruebas automatizadas o validación local. - Licencia de código y canales de comunicación.

  2. `CHANGELOG.rst`: - Registro de cambios estructurado según el estándar Keep a Changelog mediante directivas .. rubric::.

  3. Directorio `docs/` (en proyectos complejos): - Especificaciones de arquitectura interna, diagramas de secuencia o referencias completas de API.

Estrategia de Enlace y Cero Sincronización Manual

Para evitar el trabajo manual de sincronización o divergencia documental entre repositorios:

  • Enlaces Cruzados mediante URLs Canónicas: Cuando el Portal Central deba referirse a un procedimiento técnico específico (por ejemplo, cómo levantar un constructor de Koji), no copiará el manual. En su lugar, describirá el objetivo arquitectónico de la etapa y proporcionará un enlace directo al archivo correspondiente en la forja soberana:

    Para consultar los parámetros de configuración y el despliegue del constructor Mock,
consulte la `Documentación del Constructor Koji en ansible-koji <https://git.mx-os.mx/MxOS/ansible-koji/src/branch/master/docs/constructores.rst>`_.

  • Consumo de Submódulos Git en el Portal: El portal central incorpora los repositorios temáticos de documentación mediante git submodule bajo la ruta content/. La actualización del portal se reduce a actualizar el puntero de los submódulos cuando se publiquen cambios en las ramas principales correspondientes.