Directrices para contribuir a la documentación de NorTK VM

Entidad:

NorTK: Infraestructura Crítica y Soberanía Digital con Software Libre

Producto:

NorTK VM — Plataforma de Virtualización Empresarial

Sitio Web:

https://nortk.com/

Licencia:

GNU Free Documentation License, Versión 1.3 o posterior

Este documento establece las normas operativas, estándares de calidad y flujos técnicos obligatorios para colaborar en la redacción, mantenimiento y evolución del Manual de Administración de NorTK VM.

Principios editoriales indispensables

Toda contribución debe satisfacer de manera estricta los preceptos fundacionales de la Guía de Estilo de NorTK:

  • Realismo técnico y rigor empírico: Todo procedimiento debe ser reproducible en un entorno limpio de CentOS Stream (edición NorTK) y contrastarse mediante comprobaciones de verificación obligatorias.

  • Voz activa y modo imperativo directo: Redacte los pasos procedimentales como órdenes directas: Configure la red, Asigne el almacenamiento, Inicie la máquina virtual. Queda erradicada la voz pasiva.

  • Erradicación del antropomorfismo: No atribuya intenciones, emociones o pensamientos al software ni al hardware. El hipervisor ejecuta instrucciones, el kernel gestiona recursos y libvirt comunica estados.

  • Español técnico sin anglicismos superfluos: Emplee la traducción canónica consolidada en español y preserve términos estándar de la industria únicamente cuando constituyan estándar de facto en sistemas operativos POSIX/Linux.

  • Títulos limpios: Prohibido utilizar paréntesis en títulos o subtítulos. En español, los encabezados llevan mayúscula únicamente en la letra inicial y en los nombres propios o siglas. Queda prohibida la mayúscula sostenida.

  • Directiva cardinal de diagonales: Jamás coloque espacios alrededor de barras diagonales. Escriba siempre palabra/palabra, nunca palabra / palabra.

Excepciones metodológicas y paradigma GUI-First

Dado que este manual está orientado a facilitar la adopción y operación cotidiana a administradores que migran desde VMware vSphere hacia NorTK VM:

  • Paradigma GUI-first y doble carril obligatorio:

    • Todo procedimiento debe estructurarse de forma visual antes que por comandos.

    • Es mandatorio incluir la ejecución del procedimiento tanto en la consola web Cockpit como en el gestor de escritorio virt-manager.

    • Rutas de navegación jerárquica con el separador mayor que: Máquinas virtuales > Crear VM.

    • Identifique botones, pestañas, campos y etiquetas visuales estrictamente en negrita.

  • Línea de comandos en segundo término:

    • La línea de comandos jamás se descarta ni se oculta; es esencial para la automatización, la reproducibilidad y la auditoría.

    • Se sitúa en una sección estructurada al final de cada módulo procedimental (Apéndice: Automatización y auditoría por línea de comandos), con comandos deterministas (virsh, qemu-img, nmcli), argumentos explicados y salida esperada en la terminal.

  • Pipeline y criterio estricto para capturas de pantalla:

    • Consolas web: Captura automatizada mediante el script scripts/capture_all_cockpit.py empleando Chrome DevTools Protocol (CDP), viewport a densidad HiDPI (escala 2x), disparo dirigido al cuadro modal o selector específico (sin bordes de navegador) y anonimización de datos sensibles en el DOM antes del disparo.

    • Clientes de escritorio: Captura automatizada mediante el script scripts/capture_all_virtmanager.py empleando introspección PyGObject GTK3 bajo el backend headless Broadway (GDK_BACKEND=broadway), sesión aislada con dbus-run-session y renderizado nativo de widgets a superficies Cairo (win.draw(cr)).

    • Procesamiento de activos: Normalización de escala al 50% con magick convert, cuantización de color con pngquant --quality=85-95 y compresión final sin pérdidas con optipng -o7.

    • Prohibido capturar salidas de terminal, tablas de texto o archivos de configuración: todo contenido textual debe transcribirse en bloques de código .. code-block::.

    • Las imágenes deben residir en source/_static/images/, bajo el formato cockpit-<tema>-<accion>.png y virt-manager-<tema>-<accion>.png, con atributo :alt: obligatorio y exhaustivo.

Requerimientos del entorno en Fedora/CentOS Stream

Para garantizar un entorno determinista de compilación y validación, instale las herramientas necesarias mediante DNF:

# dnf install -y make python3-sphinx python3-sphinx_rtd_theme python3-sphinx-autobuild python3-rstcheck latexmk texlive-latex texlive-collection-fontsrecommended

Flujo de desarrollo y verificación

  1. Configure los hooks de Git en su copia local:

    $ make hooks

  2. Inicie el servidor de desarrollo interactivo con recarga en vivo:

    $ make dev

  3. Valide y corrija automáticamente omisiones comunes de formato en fuentes RST:

    $ make fix

  4. Ejecute la auditoría estática de sintaxis antes de preparar sus confirmaciones:

    $ make lint

  5. Genere el documento PDF completo mediante Sphinx para validar la maquetación imprimible:

    $ make latexpdf

Protocolo de control de cambios y confirmaciones

  • Formato de confirmación: Utilice el estándar Conventional Commits:

    tipo(alcance): descripción breve en imperativo

  • Tráilers obligatorios: Toda confirmación debe incluir firma formal y registro de coautoría:

    Co-authored-by: Antigravity <antigravity@google.com>
Signed-off-by: Nombre Apellido <correo@dominio.com>

Mandato de sincronización quíntuple del ciclo de vida

Toda modificación sustancial realizada en el repositorio exige la evaluación y actualización obligatoria y coordinada de los siguientes cinco componentes:

  1. GEMINI.md: Directivas de ingeniería y decisiones arquitectónicas del repositorio.

  2. .agents/skills/nortk-vm-doc/SKILL.md: Guía de habilidades compartida del proyecto.

  3. CONTRIBUTING.rst: Directrices de contribución y estándares para el equipo.

  4. CHANGELOG.rst: Registro cronológico en la Bitácora bajo Keep a Changelog y Semantic Versioning.

  5. README.rst: Documentación principal e índice del repositorio.

Licencia de las contribuciones

Al colaborar en este proyecto, usted acepta de forma vinculante que toda su documentación, código, hojas de estilo y artefactos complementarios se publiquen bajo los términos de la Licencia de Documentación Libre de GNU (GNU Free Documentation License), Versión 1.3 o cualquier versión posterior aprobada por la Free Software Foundation.