Guía de Estilo para READMEs de Repositorio

Estándares de Estructura y Redacción para Repositorios de MxOS

Autores:
Organización:

Fundación MxOS, A.C.

Fecha:

Septiembre 2026

Estado:

Estándar Activo

Descripción y Alcance

Este documento complementa la Guía de Estilo General y define la estructura obligatoria que debe contener el archivo README.rst en la raíz de cualquier repositorio del ecosistema de la Fundación MxOS.

Diferencias con Documentos Temáticos

A diferencia de los documentos extensos del portal, el archivo README.rst opera como la portada técnica inmediata para desarrolladores en la forja Git:

  • El título principal lleva sobrerrayado y subrayado formal con signos de igual (=), coincidiendo exactamente en longitud de caracteres.

  • El documento debe priorizar la información densa y procesable: instrucciones directas para compilar, probar y desplegar, omitiendo introducciones retóricas o decorativas.

Secciones Obligatorias en un README.rst

Todo repositorio de la Fundación debe organizar su README.rst con las siguientes secciones canónicas:

  1. Descripción: Resumen ejecutivo del componente: qué problema resuelve, su arquitectura de alto nivel y su rol dentro de la distribución MxOS.

  2. Requisitos Previos: Dependencias de software, herramientas de compilación necesarias (ej. compilador GCC/Clang, runtime Crystal, paquetes Mock, Ansible, Podman) y requerimientos mínimos de hardware/sistema operativo.

  3. Procedimiento de Compilación y Ejecución: Comandos exactos y reproducibles para clonar, configurar, compilar y ejecutar el proyecto localmente. Se deben utilizar bloques de código tipados (.. code-block:: bash).

  4. Validación y Pruebas: Instrucciones para ejecutar suites de pruebas unitarias, linters de código estático (ej. Ameba, ShellCheck, rstcheck) o validaciones de integración.

  5. Estructura del Proyecto: Árbol de directorios principal comentando la responsabilidad de cada submódulo o directorio.

  6. Licencia y Contacto: Especificación clara de la licencia de código abierto aplicable (ej. GPLv3, Apache 2.0, CC-BY-SA 4.0) y canales institucionales de soporte o reporte de vulnerabilidades.