# AGENTS.md ## Descripción del Proyecto Este es un repositorio educativo para enseñar los fundamentos del desarrollo web a principiantes. El currículum es un curso integral de 12 semanas desarrollado por Microsoft Cloud Advocates, que incluye 24 lecciones prácticas sobre JavaScript, CSS y HTML. ### Componentes Clave - **Contenido Educativo**: 24 lecciones estructuradas organizadas en módulos basados en proyectos - **Proyectos Prácticos**: Terrarium, Juego de mecanografía, Extensión de navegador, Juego espacial, Aplicación bancaria, Editor de código y Asistente de chat con IA - **Cuestionarios Interactivos**: 48 cuestionarios con 3 preguntas cada uno (evaluaciones pre y post lección) - **Soporte Multilenguaje**: Traducciones automáticas en más de 50 idiomas vía GitHub Actions - **Tecnologías**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (para proyectos de IA) ### Arquitectura - Repositorio educativo con estructura basada en lecciones - Cada carpeta de lección contiene README, ejemplos de código y soluciones - Proyectos independientes en directorios separados (quiz-app, varios proyectos de lecciones) - Sistema de traducción usando GitHub Actions (co-op-translator) - Documentación servida vía Docsify y disponible en PDF ## Comandos de Configuración Este repositorio está principalmente para consumo de contenido educativo. Para trabajar con proyectos específicos: ### Configuración Principal del Repositorio ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` ### Configuración de Quiz App (Vue 3 + Vite) ```bash cd quiz-app npm install npm run dev # Iniciar servidor de desarrollo npm run build # Construir para producción npm run lint # Ejecutar ESLint ``` ### API para Proyecto Bancario (Node.js + Express) ```bash cd 7-bank-project/api npm install npm start # Iniciar servidor API npm run lint # Ejecutar ESLint npm run format # Formatear con Prettier ``` ### Proyectos de Extensión para Navegador ```bash cd 5-browser-extension/solution npm install # Sigue las instrucciones específicas del navegador para cargar extensiones ``` ### Proyectos de Juego Espacial ```bash cd 6-space-game/solution npm install # Abre index.html en el navegador o usa Live Server ``` ### Proyecto de Chat (Backend en Python) ```bash cd 9-chat-project/solution/backend/python pip install openai # Establecer la variable de entorno GITHUB_TOKEN python api.py ``` ## Flujo de Desarrollo ### Para Contribuidores de Contenido 1. **Hacer fork del repositorio** a tu cuenta de GitHub 2. **Clonar tu fork** localmente 3. **Crear una nueva rama** para tus cambios 4. Realizar cambios en contenido de lecciones o ejemplos de código 5. Probar cualquier cambio de código en los directorios de proyectos relevantes 6. Enviar pull requests siguiendo las directrices de contribución ### Para Estudiantes 1. Hacer fork o clonar el repositorio 2. Navegar secuencialmente por los directorios de lecciones 3. Leer los archivos README de cada lección 4. Completar cuestionarios pre-lección en https://ff-quizzes.netlify.app/web/ 5. Trabajar con ejemplos de código en las carpetas de las lecciones 6. Completar tareas y desafíos 7. Realizar cuestionarios post-lección ### Desarrollo en Vivo - **Documentación**: Ejecutar `docsify serve` en la raíz (puerto 3000) - **Quiz App**: Ejecutar `npm run dev` en el directorio quiz-app - **Proyectos**: Usar extensión Live Server de VS Code para proyectos HTML - **Proyectos API**: Ejecutar `npm start` en los directorios API respectivos ## Instrucciones para Pruebas ### Pruebas de Quiz App ```bash cd quiz-app npm run lint # Verificar problemas de estilo de código npm run build # Verificar que la compilación sea exitosa ``` ### Pruebas de API Bancaria ```bash cd 7-bank-project/api npm run lint # Verificar problemas de estilo de código node server.js # Verificar que el servidor arranque sin errores ``` ### Enfoque General para Pruebas - Este repositorio educativo no cuenta con pruebas automatizadas completas - Las pruebas manuales se centran en: - Que los ejemplos de código se ejecuten sin errores - Que los enlaces en la documentación funcionen correctamente - Que las compilaciones de proyectos finalicen sin errores - Que los ejemplos sigan las mejores prácticas ### Chequeos Previo al Envío - Ejecutar `npm run lint` en directorios con package.json - Verificar que los enlaces en markdown sean válidos - Probar ejemplos de código en navegador o Node.js - Comprobar que las traducciones mantengan la estructura adecuada ## Guías de Estilo de Código ### JavaScript - Usar sintaxis moderna ES6+ - Seguir configuraciones standard de ESLint proporcionadas en proyectos - Usar nombres significativos para variables y funciones para claridad educativa - Añadir comentarios que expliquen conceptos para los estudiantes - Formatear usando Prettier donde esté configurado ### HTML/CSS - Elementos semánticos HTML5 - Principios de diseño responsivo - Convenciones claras de nombres de clases - Comentarios que expliquen técnicas CSS para estudiantes ### Python - Guías de estilo PEP 8 - Código claro y educativo - Anotaciones de tipo donde sean útiles para el aprendizaje ### Documentación en Markdown - Jerarquía clara de encabezados - Bloques de código con especificación de lenguaje - Enlaces a recursos adicionales - Capturas de pantalla e imágenes en directorios `images/` - Texto alternativo para imágenes para accesibilidad ### Organización de Archivos - Lecciones numeradas secuencialmente (1-getting-started-lessons, 2-js-basics, etc.) - Cada proyecto tiene `solution/` y a menudo `start/` o `your-work/` - Imágenes almacenadas en carpetas `images/` específicas por lección - Traducciones en la estructura `translations/{language-code}/` ## Construcción y Despliegue ### Despliegue de Quiz App (Azure Static Web Apps) La quiz-app está configurada para despliegue en Azure Static Web Apps: ```bash cd quiz-app npm run build # Crea la carpeta dist/ # Despliega mediante el flujo de trabajo de GitHub Actions al hacer push en main ``` Configuración de Azure Static Web Apps: - **Ubicación de la app**: `/quiz-app` - **Ubicación de salida**: `dist` - **Flujo de trabajo**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` ### Generación de Documentación PDF ```bash npm install # Instalar docsify-to-pdf npm run convert # Generar PDF desde docs ``` ### Documentación con Docsify ```bash npm install -g docsify-cli # Instalar Docsify globalmente docsify serve # Servir en localhost:3000 ``` ### Compilaciones específicas de proyectos Cada directorio de proyecto puede tener su propio proceso de compilación: - Proyectos Vue: `npm run build` crea paquetes para producción - Proyectos estáticos: No tienen paso de compilación, se sirven archivos directamente ## Directrices para Pull Requests ### Formato del Título Usar títulos claros y descriptivos indicando la área de cambio: - `[Quiz-app] Añadir nuevo cuestionario para la lección X` - `[Lesson-3] Corregir error tipográfico en proyecto terrarium` - `[Translation] Añadir traducción al español para la lección 5` - `[Docs] Actualizar instrucciones de configuración` ### Verificaciones Requeridas Antes de enviar un PR: 1. **Calidad del código**: - Ejecutar `npm run lint` en directorios afectados - Corregir todos los errores y advertencias de linting 2. **Verificación de compilación**: - Ejecutar `npm run build` si aplica - Asegurar que no hay errores en la compilación 3. **Validación de enlaces**: - Probar todos los enlaces markdown - Verificar referencias de imágenes 4. **Revisión de contenido**: - Revisar ortografía y gramática - Asegurar que ejemplos de código sean correctos y educativos - Verificar que las traducciones mantengan el significado original ### Requisitos para Contribuir - Aceptar Microsoft CLA (verificación automática en primer PR) - Seguir el [Código de Conducta de Código Abierto de Microsoft](https://opensource.microsoft.com/codeofconduct/) - Consultar [CONTRIBUTING.md](./CONTRIBUTING.md) para directrices detalladas - Referenciar números de issues en la descripción del PR si aplica ### Proceso de Revisión - Los PR son revisados por mantenedores y la comunidad - Se prioriza la claridad educativa - Los ejemplos de código deben seguir mejores prácticas actuales - Las traducciones se revisan para exactitud y adecuación cultural ## Sistema de Traducción ### Traducción Automática - Usa GitHub Actions con el workflow co-op-translator - Traduce automáticamente a más de 50 idiomas - Archivos fuente en directorios principales - Archivos traducidos en `translations/{language-code}/` ### Agregar Mejoras Manuales de Traducción 1. Localizar archivo en `translations/{language-code}/` 2. Mejorar manteniendo la estructura 3. Asegurar que los ejemplos de código sigan funcionando 4. Probar cualquier cuestionario localizado ### Metadatos de Traducción Los archivos traducidos incluyen encabezado de metadatos: ```markdown ``` ## Depuración y Resolución de Problemas ### Problemas Comunes **La app de cuestionarios no arranca**: - Verificar versión de Node.js (recomendada v14+) - Eliminar `node_modules` y `package-lock.json`, ejecutar de nuevo `npm install` - Revisar conflictos de puertos (por defecto: Vite usa puerto 5173) **El servidor API no inicia**: - Verificar que la versión de Node.js sea compatible (node >=10) - Comprobar si el puerto está en uso - Asegurar que todas las dependencias estén instaladas con `npm install` **La extensión del navegador no carga**: - Verificar que el manifest.json esté bien formado - Revisar la consola del navegador para errores - Seguir instrucciones específicas del navegador para instalar extensiones **Problemas con el proyecto de chat en Python**: - Asegurar que el paquete OpenAI esté instalado: `pip install openai` - Verificar que la variable de entorno GITHUB_TOKEN esté configurada - Comprobar permisos de acceso a GitHub Models **Docsify no sirve la documentación**: - Instalar docsify-cli globalmente: `npm install -g docsify-cli` - Ejecutar desde el directorio raíz del repositorio - Confirmar que `docs/_sidebar.md` exista ### Consejos para el Entorno de Desarrollo - Usar VS Code con extensión Live Server para proyectos HTML - Instalar extensiones ESLint y Prettier para formateo consistente - Usar DevTools del navegador para depurar JavaScript - Para proyectos Vue, instalar extensión Vue DevTools para navegador ### Consideraciones de Rendimiento - Gran cantidad de archivos traducidos (más de 50 idiomas) hace que clonaciones completas sean grandes - Usar clonación superficial si solo se trabaja con contenido: `git clone --depth 1` - Excluir traducciones de búsquedas al trabajar con contenido en inglés - Los procesos de compilación pueden ser lentos en la primera ejecución (npm install, compilación Vite) ## Consideraciones de Seguridad ### Variables de Entorno - Las claves API nunca deben subirse al repositorio - Usar archivos `.env` (ya incluidos en `.gitignore`) - Documentar variables de entorno necesarias en los READMEs de los proyectos ### Proyectos en Python - Usar entornos virtuales: `python -m venv venv` - Mantener dependencias actualizadas - Los tokens de GitHub deben tener permisos mínimos necesarios ### Acceso a GitHub Models - Se requieren Tokens de Acceso Personal (PAT) para GitHub Models - Los tokens deben almacenarse como variables de entorno - Nunca subir tokens o credenciales al repositorio ## Notas Adicionales ### Público Objetivo - Principiantes completos en desarrollo web - Estudiantes y autodidactas - Profesores que usan el currículum en aulas - Contenido diseñado para accesibilidad y desarrollo gradual de habilidades ### Filosofía Educativa - Enfoque basado en aprendizaje por proyectos - Chequeos frecuentes de conocimiento (cuestionarios) - Ejercicios prácticos de codificación - Ejemplos de aplicaciones del mundo real - Enfoque en fundamentos antes que frameworks ### Mantenimiento del Repositorio - Comunidad activa de aprendices y contribuyentes - Actualizaciones regulares en dependencias y contenido - Issues y discusiones monitoreadas por mantenedores - Actualizaciones de traducción automatizadas vía GitHub Actions ### Recursos Relacionados - [Módulos Microsoft Learn](https://docs.microsoft.com/learn/) - [Recursos para estudiantes hub](https://docs.microsoft.com/learn/student-hub/) - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recomendado para aprendices - Cursos adicionales: IA generativa, Ciencia de datos, ML, currículos IoT disponibles ### Trabajo con Proyectos Específicos Para instrucciones detalladas de proyectos individuales, consultar los archivos README en: - `quiz-app/README.md` - aplicación de cuestionarios en Vue 3 - `7-bank-project/README.md` - aplicación bancaria con autenticación - `5-browser-extension/README.md` - desarrollo de extensión de navegador - `6-space-game/README.md` - desarrollo de juego en canvas - `9-chat-project/README.md` - proyecto de asistente de chat IA ### Estructura Monorepo Aunque no es un monorepo tradicional, este repositorio contiene múltiples proyectos independientes: - Cada lección es autónoma - Los proyectos no comparten dependencias - Se puede trabajar en proyectos individuales sin afectar otros - Clonar el repositorio completo para experiencia completa del currículum --- **Descargo de responsabilidad**: Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No nos hacemos responsables de malentendidos o interpretaciones erróneas derivadas del uso de esta traducción.