Saltar a contenido

README de entrega — DAW-U1.-Practica001

Este archivo puede ser la semilla que de lugar al README.md del repositorio de tu proyecto intermodular. Sustituye los textos entre corchetes por información real y elimina las instrucciones de ayuda antes de entregar.

Estado de la entrega

  • PENDIENTE: falta completar el apartado o añadir evidencia.
  • ENTREGADO: el apartado está completo y tiene enlaces o evidencias verificables.
  • Si algo está bloqueado, déjalo como PENDIENTE y describe el motivo.
  • La publicación en GitHub Pages es obligatoria; no marques ese requisito como «no aplica».

  • No incluyas claves privadas, tokens, contraseñas ni valores de secretos.

  • Estado general: PENDIENTE

  • Estudiante o integrantes: [NOMBRES]
  • Proyecto intermodular: [NOMBRE DEL PROYECTO]
  • Repositorio: [URL]

La Parte 1 del enunciado se realiza en clase y no se entrega. Este README documenta los entregables obligatorios del proyecto intermodular.

1. Entregable 1 — Repositorio y workflow funcionando

Estado del entregable 1: PENDIENTE

  • URL del repositorio: [URL]
  • Visibilidad: [Público / Privado]
  • Acceso del profesor: [Si el repositorio es privado, confirma que se ha añadido al profesor como colaborador.]
  • Archivo del workflow: [Ruta dentro de .github/workflows/]
  • Ejecución correcta de GitHub Actions: [Enlace a un run satisfactorio]
  • Evento que inicia el workflow: [Por ejemplo, push, pull_request o workflow_dispatch]

2. Entregable 2 — Documentación HTML y en otro formato

Estado del entregable 2: PENDIENTE

Formato Archivo o ruta dentro de docs/ Enlace para consultarlo Cómo se genera o publica
HTML [RUTA] [ENLACE] [COMANDO / PASO DEL WORKFLOW]
[Segundo formato: PDF, Markdown u otro] [RUTA] [ENLACE] [COMANDO / PASO DEL WORKFLOW]
  • Generación local comprobada: [Describe cómo generaste y verificaste los archivos fuera de GitHub.]
  • Cómo se almacenan los resultados: [Artefactos de Actions, commit de docs/ o ambos.]
  • Evidencia: [Enlace, listado de archivos o captura.]

3. Entregable 3 — README del proyecto, proceso y cuestionario

Estado del entregable 3: PENDIENTE

Completa los apartados 3.a–3.g y responde el cuestionario CE a–h al final de este bloque. El punto 3 se considera entregado cuando todas esas respuestas y evidencias estén completas.

3.a. Herramientas y comandos

Estado: PENDIENTE

Herramienta o dependencia Versión Uso
[Lenguaje / runtime] [VERSIÓN] [USO]
[Generador de documentación] [VERSIÓN] [QUÉ FORMATOS GENERA]
[Editor de código o Markdown] [NOMBRE/VERSIÓN] [USO]
[Otras dependencias] [VERSIÓN] [USO]

Registra los comandos reales que usaste para instalar dependencias y generar localmente los dos formatos:

# Instalar dependencias
[COMANDO REAL]

# Generar HTML
[COMANDO REAL]

# Generar el segundo formato
[COMANDO REAL]

3.b. Código fuente documentado

Estado: PENDIENTE

  • Estilo de documentación: [JavaDoc, KDoc, Google Style, reStructuredText u otro]
  • Archivo fuente documentado: [ENLACE RELATIVO AL CÓDIGO]
  • Fragmento con la documentación estructurada:
[PEGA UN FRAGMENTO REAL CON LAS ETIQUETAS O ESTRUCTURA QUE PROCESA TU GENERADOR]
  • Documentación generada a partir de ese fragmento: [ENLACE A LA PÁGINA O SECCIÓN]

3.c. Formatos generados y enlaces

Estado: PENDIENTE

Enlaza aquí los resultados generados para que se puedan abrir desde el README:

  • HTML: [ENLACE]
  • Segundo formato: [FORMATO Y ENLACE]
  • Artefactos de GitHub Actions o carpeta versionada: [ENLACE O RUTA]

3.d. Funcionamiento del workflow y colaboración

Estado: PENDIENTE

Describe los pasos del workflow en el orden en que ocurren:

  1. Evento y rama: [QUÉ LO DISPARA]
  2. Preparación del entorno: [CHECKOUT, RUNTIME Y DEPENDENCIAS]
  3. Generación: [CÓMO PRODUCE HTML Y EL SEGUNDO FORMATO]
  4. Almacenamiento o publicación: [ARTEFACTOS, COMMIT DE docs/ U OTRA SALIDA]
  5. Comprobación: [CÓMO SABES QUE EL RUN Y LOS RESULTADOS SON CORRECTOS]

Colaboración con GitHub: [Explica cómo ramas, pull requests, revisiones, checks y protección de ramas ayudan a mantener el README y la documentación cuando colaboran varias personas.]

3.e. Mensajes de commit

Estado: PENDIENTE

Hash o enlace Mensaje real Qué cambio demuestra
[HASH / URL] [MENSAJE] [CAMBIO]
[HASH / URL] [MENSAJE] [CAMBIO]

Justificación: [Explica por qué los mensajes son claros y descriptivos y cómo evidencian la mejora del workflow.]

3.f. Acceso, seguridad y SSH

Estado: PENDIENTE

  • Permisos del repositorio: [Quién puede leer o modificar el repositorio y qué roles se han configurado.]
  • Protección de ramas o revisiones: [Configuración usada o «No configurada».]
  • Secretos de Actions: [Nombres y uso de secretos; nunca incluyas sus valores.]
  • Configuración SSH: [Indica dónde se añadió la clave pública.]
  • Prueba SSH: [Enlace a captura o transcripción de ssh -T git@github.com]

No pegues aquí la clave privada ni tokens de acceso.

3.g. Clonar y reproducir la generación

Estado: PENDIENTE

git clone [URL DEL REPOSITORIO]
cd [CARPETA DEL PROYECTO]
[COMANDO PARA INSTALAR DEPENDENCIAS]
[COMANDO PARA GENERAR LA DOCUMENTACIÓN]
  • Requisitos previos: [Sistema operativo, runtime, herramientas y dependencias.]
  • Resultado esperado: [Rutas o enlaces a los archivos generados.]
  • Cómo volver a ejecutar el workflow: [Evento, rama o instrucciones.]

Cuestionario de evaluación CE a–h

Responde todos los apartados. Puedes resumir la información ya documentada en 3.a–3.g y enlazar esa sección como evidencia.

CE a. Herramientas de generación

  • Estado: PENDIENTE
  • Pregunta: ¿Qué herramienta o generador utilizaste en el workflow para crear la documentación en /docs?
  • Respuesta: [HERRAMIENTA Y FUNCIÓN]
  • Evidencia: [ENLACE A 3.a O AL WORKFLOW]

CE b. Documentación de componentes

  • Estado: PENDIENTE
  • Pregunta: Muestra un fragmento del código fuente con comentarios o docstrings estructurados y comenta el estilo utilizado.
  • Respuesta: [ENLACE A 3.b Y EXPLICACIÓN DEL ESTILO]
  • Evidencia: [ENLACE A LA DOCUMENTACIÓN GENERADA]

CE c. Formatos

  • Estado: PENDIENTE
  • Pregunta: ¿Qué segundo formato generaste además de HTML? Explica qué configuración o comandos lo producen.
  • Respuesta: [FORMATO, CONFIGURACIÓN Y COMANDOS]
  • Evidencia: [ENLACE A 3.c]

CE d. Colaboración

  • Estado: PENDIENTE
  • Pregunta: ¿Cómo facilita GitHub mantener el README y la documentación de /docs cuando colaboran varias personas?
  • Respuesta: [RAMAS, PULL REQUESTS, REVISIONES, CHECKS Y PERMISOS]
  • Evidencia: [ENLACE A 3.d]

CE e. Control de versiones

  • Estado: PENDIENTE
  • Pregunta: Muestra mensajes de commit que evidencien el nuevo workflow. ¿Son claros y descriptivos? Justifícalo.
  • Respuesta: [MENSAJES REALES Y JUSTIFICACIÓN]
  • Evidencia: [ENLACE A 3.e]

CE f. Accesibilidad y seguridad

  • Estado: PENDIENTE
  • Pregunta: ¿Qué medidas o configuraciones garantizan que solo personal autorizado acceda al código y la documentación generada?
  • Respuesta: [VISIBILIDAD, PERMISOS, SECRETOS Y PROTECCIÓN DE RAMAS]
  • Evidencia: [ENLACE A 3.f; NO INCLUYAS SECRETOS]

CE g. Instalación, configuración y uso

  • Estado: PENDIENTE
  • Pregunta: ¿Dónde explicas en este README el funcionamiento del workflow y dónde describes las herramientas y comandos?
  • Respuesta: [INDICA LAS SECCIONES 3.a, 3.d Y 3.g, U OTRAS QUE CORRESPONDAN]

CE h. Integración continua

  • Estado: PENDIENTE
  • Pregunta: ¿Por qué se clasifica el workflow como CI? ¿Qué evento dispara automáticamente la generación o actualización?
  • Respuesta: [QUÉ VERIFICA O GENERA Y QUÉ EVENTO LO ACTIVA]
  • Evidencia: [ENLACE A 3.d Y AL RUN DE ACTIONS]

4. Entregable 4 — Publicación obligatoria con MkDocs y GitHub Pages

Estado: PENDIENTE

No marques este entregable como completo hasta que la página pública sea accesible y el workflow de despliegue haya terminado correctamente.

  • URL pública de GitHub Pages: [URL]
  • Workflow de construcción y despliegue: [RUTA DENTRO DE .github/workflows/]
  • Acción y rama de publicación: [ACCIÓN USADA Y RAMA, POR EJEMPLO gh-pages]
  • Ejecución correcta de Actions: [ENLACE AL RUN]
  • Comprobación del sitio: [CONFIRMA QUE ABRISTE LA URL Y QUE CARGA LA DOCUMENTACIÓN]
  • Si sigue pendiente: [ERROR O BLOQUEO Y SIGUIENTE PASO]

Conclusiones

[Resume qué aprendiste sobre generadores, formatos, GitHub Actions y control de versiones. Indica una mejora posible para el workflow.]

Revisión final

  • Entregable 1: repositorio accesible y workflow funcionando, con un run visible.
  • Entregable 2: HTML y segundo formato generados y accesibles.
  • Entregable 3: secciones 3.a–3.g completas, cuestionario CE a–h respondido y evidencias enlazadas1
  • Entregable 4: sitio publicado en GitHub Pages y workflow de despliegue comprobado.