14 KiB

Raw Permalink Blame History

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

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

Configuración de Quiz App (Vue 3 + Vite)

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)

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

cd 5-browser-extension/solution
npm install
# Sigue las instrucciones específicas del navegador para cargar extensiones

Proyectos de Juego Espacial

cd 6-space-game/solution
npm install
# Abre index.html en el navegador o usa Live Server

Proyecto de Chat (Backend en Python)

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

Hacer fork del repositorio a tu cuenta de GitHub
Clonar tu fork localmente
Crear una nueva rama para tus cambios
Realizar cambios en contenido de lecciones o ejemplos de código
Probar cualquier cambio de código en los directorios de proyectos relevantes
Enviar pull requests siguiendo las directrices de contribución

Para Estudiantes

Hacer fork o clonar el repositorio
Navegar secuencialmente por los directorios de lecciones
Leer los archivos README de cada lección
Completar cuestionarios pre-lección en https://ff-quizzes.netlify.app/web/
Trabajar con ejemplos de código en las carpetas de las lecciones
Completar tareas y desafíos
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

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

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:

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

npm install                    # Instalar docsify-to-pdf
npm run convert               # Generar PDF desde docs

Documentación con Docsify

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:

Calidad del código:
- Ejecutar npm run lint en directorios afectados
- Corregir todos los errores y advertencias de linting
Verificación de compilación:
- Ejecutar npm run build si aplica
- Asegurar que no hay errores en la compilación
Validación de enlaces:
- Probar todos los enlaces markdown
- Verificar referencias de imágenes
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
Consultar 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

Localizar archivo en translations/{language-code}/
Mejorar manteniendo la estructura
Asegurar que los ejemplos de código sigan funcionando
Probar cualquier cuestionario localizado

Metadatos de Traducción

Los archivos traducidos incluyen encabezado de metadatos:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

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
Recursos para estudiantes hub
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. 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.

14 KiB Raw Permalink Blame History