14 KiB

Raw Permalink Blame History

AGENTS.md

Descripción general del proyecto

Este es un repositorio de currículo educativo para enseñar los fundamentos del desarrollo web a principiantes. El currículo 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: Terrario, 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 antes/después de la lección)
Soporte multilingüe: Traducciones automáticas a más de 50 idiomas mediante 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 el 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 la aplicación de cuestionarios (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 del 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 extensiones de navegador

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

Proyectos del 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 trabajo de desarrollo

Para colaboradores de contenido

Haz un fork del repositorio a tu cuenta de GitHub
Clona tu fork localmente
Crea una nueva rama para tus cambios
Realiza cambios en el contenido de las lecciones o en los ejemplos de código
Prueba cualquier cambio de código en los directorios de proyectos relevantes
Envía pull requests siguiendo las directrices de contribución

Para estudiantes

Haz fork o clona el repositorio
Navega a los directorios de las lecciones de forma secuencial
Lee los archivos README de cada lección
Completa los cuestionarios previos en https://ff-quizzes.netlify.app/web/
Trabaja los ejemplos de código en las carpetas de las lecciones
Completa tareas y desafíos
Realiza los cuestionarios posteriores a la lección

Desarrollo en vivo

Documentación: Ejecuta docsify serve en la raíz (puerto 3000)
Aplicación de cuestionarios: Ejecuta npm run dev en el directorio quiz-app
Proyectos: Usa la extensión Live Server de VS Code para proyectos HTML
Proyectos API: Ejecuta npm start en los directorios API respectivos

Instrucciones de pruebas

Pruebas de la aplicación de cuestionarios

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 la API bancaria

cd 7-bank-project/api
npm run lint       # Verificar problemas de estilo de código
node server.js     # Verificar que el servidor inicie sin errores

Enfoque general de pruebas

Este es un repositorio educativo sin pruebas automatizadas completas
Las pruebas manuales se enfocan en:
- Ejecución de ejemplos de código sin errores
- Funcionalidad correcta de enlaces en la documentación
- Construcción exitosa de proyectos
- Ejemplos que siguen buenas prácticas

Verificaciones antes de enviar

Ejecuta npm run lint en directorios con package.json
Verifica que los enlaces markdown sean válidos
Prueba ejemplos de código en navegador o Node.js
Comprueba que las traducciones mantienen la estructura correcta

Directrices de estilo de código

JavaScript

Usar sintaxis moderna ES6+
Seguir configuraciones estándar de ESLint proporcionadas en los proyectos
Usar nombres de variables y funciones significativos 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 nomenclatura de clases
Comentarios que expliquen técnicas CSS para estudiantes

Python

Guías de estilo PEP 8
Código claro y educativo
Uso de anotaciones de tipo donde ayuden al aprendizaje

Documentación 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 en imágenes para accesibilidad

Organización de archivos

Lecciones numeradas secuencialmente (1-getting-started-lessons, 2-js-basics, etc.)
Cada proyecto tiene directorios solution/ y a menudo start/ o your-work/
Imágenes guardadas en carpetas images/ específicas de cada lección
Traducciones en la estructura translations/{language-code}/

Construcción y despliegue

Despliegue de la aplicación de cuestionarios (Azure Static Web Apps)

La quiz-app está configurada para el 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 a main

Configuración de Azure Static Web Apps:

Ubicación de la aplicación: /quiz-app
Ubicación de salida: dist
Flujo de trabajo: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generación de PDF de documentación

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

Documentación Docsify

npm install -g docsify-cli    # Instalar Docsify globalmente
docsify serve                 # Servir en localhost:3000

Construcciones específicas de proyectos

Cada directorio de proyecto puede tener su propio proceso de construcción:

Proyectos Vue: npm run build crea paquetes de producción
Proyectos estáticos: No hay paso de construcción, servir archivos directamente

Directrices para pull request

Formato del título

Usa títulos claros y descriptivos que indiquen el área del 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
Verificación de construcción:
- Ejecutar npm run build si aplica
- Asegurar que no haya errores de construcción
Validación de enlaces:
- Probar todos los enlaces markdown
- Verificar que las imágenes se cargan correctamente
Revisión de contenido:
- Corregir ortografía y gramática
- Confirmar que ejemplos de código sean correctos y educativos
- Verificar que las traducciones mantengan el significado original

Requisitos de contribución

Aceptar el CLA de Microsoft (verificación automática en el primer PR)
Seguir el Código de conducta de código abierto de Microsoft
Consultar CONTRIBUTING.md para pautas detalladas
Referenciar números de issues en la descripción del PR si aplica

Proceso de revisión

PRs revisados por mantenedores y comunidad
Prioridad a la claridad educativa
Ejemplos de código deben seguir buenas prácticas actuales
Traducciones revisadas por precisión y adecuación cultural

Sistema de traducción

Traducción automatizada

Usa GitHub Actions con el flujo co-op-translator
Traduce automáticamente a más de 50 idiomas
Archivos fuente en directorios principales
Archivos traducidos en translations/{language-code}/

Añadir mejoras manuales a las traducciones

Localiza el archivo en translations/{language-code}/
Realiza mejoras preservando la estructura
Asegura que los ejemplos de código sigan funcionando
Prueba cualquier contenido localizado de cuestionarios

Metadatos de traducción

Los archivos traducidos incluyen cabecera de metadatos:

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

Depuración y solución de problemas

Problemas comunes

La aplicación de cuestionarios no inicia:

Verificar versión de Node.js (recomendado v14+)
Borrar node_modules y package-lock.json, ejecutar npm install nuevamente
Revisar conflictos de puerto (por defecto: Vite usa puerto 5173)

El servidor API no arranca:

Verificar que la versión de Node.js cumple mínimo (node >=10)
Comprobar si el puerto ya está en uso
Asegurar que todas las dependencias están instaladas con npm install

La extensión de navegador no carga:

Verificar que manifest.json está correctamente formateado
Revisar la consola del navegador por errores
Seguir instrucciones específicas del navegador para instalación de extensiones

Problemas en proyecto de chat Python:

Asegurar que el paquete OpenAI esté instalado: pip install openai
Verificar que la variable de entorno GITHUB_TOKEN esté configurada
Revisar permisos de acceso de modelos de GitHub

Docsify no sirve la documentación:

Instalar docsify-cli globalmente: npm install -g docsify-cli
Ejecutar desde el directorio raíz del repositorio
Verificar que docs/_sidebar.md exista

Consejos para el entorno de desarrollo

Usar VS Code con la extensión Live Server para proyectos HTML
Instalar extensiones ESLint y Prettier para formato consistente
Usar DevTools del navegador para depurar JavaScript
Para proyectos Vue, instalar la extensión Vue DevTools

Consideraciones de rendimiento

El gran número de archivos traducidos (50+ idiomas) hace que los clones completos sean grandes
Usar clonación superficial si solo se trabaja con contenido: git clone --depth 1
Excluir traducciones de búsquedas cuando se trabaja con contenido en inglés
Los procesos de construcció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 ser comprometidas en el repositorio
Usar archivos .env (ya están en .gitignore)
Documentar variables de entorno requeridas en los README de los proyectos

Proyectos en Python

Usar entornos virtuales: python -m venv venv
Mantener dependencias actualizadas
Tokens de GitHub deben tener permisos mínimos necesarios

Acceso a modelos de GitHub

Se requieren Tokens de Acceso Personal (PAT) para modelos de GitHub
Los tokens deben guardarse como variables de entorno
Nunca comprometer tokens o credenciales

Notas adicionales

Público objetivo

Principiantes completos en desarrollo web
Estudiantes y autodidactas
Profesores usando el currículo en aulas
Contenido diseñado para accesibilidad y construcción gradual de habilidades

Filosofía educativa

Enfoque de aprendizaje basado en proyectos
Revisiones frecuentes de conocimiento (cuestionarios)
Ejercicios prácticos de programación
Ejemplos de aplicación en el mundo real
Enfoque en fundamentos antes que frameworks

Mantenimiento del repositorio

Comunidad activa de aprendices y colaboradores
Actualizaciones regulares de dependencias y contenido
Issues y discusiones monitoreadas por mantenedores
Actualización de traducciones automatizadas mediante GitHub Actions

Recursos relacionados

Módulos Microsoft Learn
Recursos Student Hub
GitHub Copilot recomendado para estudiantes
Cursos adicionales: Currículos de IA generativa, Ciencia de datos, ML, IoT disponibles

Trabajar con proyectos específicos

Para instrucciones detalladas sobre proyectos individuales, consulta 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 extensiones para navegador
6-space-game/README.md - Desarrollo de juego basado en Canvas
9-chat-project/README.md - Proyecto de asistente de chat con IA

Estructura de monorepositorio

Aunque no es un monorepo tradicional, este repositorio contiene múltiples proyectos independientes:

Cada lección es autónoma
Los proyectos no comparten dependencias
Trabaja en proyectos individuales sin afectar otros
Clona el repositorio completo para la experiencia completa del currículo

Descargo de responsabilidad: Este documento ha sido traducido utilizando el servicio de traducción por IA Co-op Translator. Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automáticas 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 realizada por humanos. No nos hacemos responsables de malentendidos o interpretaciones erróneas derivadas del uso de esta traducción.

14 KiB Raw Permalink Blame History