================================= Política de Documentación de MxOS ================================= ---------------------------------------------------------------- Fronteras de Contenido, Gobernanza Editorial y Modelo de Fuentes ---------------------------------------------------------------- :Autores: - Rénich Bon Ćirić :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 ================================================================ .. list-table:: :header-rows: 1 :widths: 20 40 40 * - 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: .. code-block:: rst Para consultar los parámetros de configuración y el despliegue del constructor Mock, consulte la `Documentación del Constructor Koji en ansible-koji `_. * **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.