Contribuir
Añadir un proyecto
Todos los proyectos reales que ves aquí empezaron como un archivo markdown en la pull request de alguien. Esta página enumera exactamente qué cambiar, en orden, y los comandos para comprobar tu trabajo antes de enviarlo.
-
Comprueba tus herramientas
Antes de nada, asegúrate de tener lo que el proyecto necesita. Necesitas Node 22 o superior (el sitio se construye con él) y git. Si un comando de abajo no imprime nada, esa herramienta falta.
- node --version
- git --version
- Comprueba la versión de Node y de git con los comandos de abajo.
- Si Node es anterior a 22, instala el LTS actual desde nodejs.org antes de continuar.
Deberías vernode --version # v22.x or newer git --version # any recent version -
Haz un fork del repositorio
Un fork es tu propia copia del repositorio, en tu cuenta de GitHub. Trabajas ahí, así que nada de lo que hagas puede afectar al sitio en vivo.
- Abre github.com/abderrahim-lectures/python-data-analysis-course.
- Pulsa el botón Fork arriba a la derecha.
- Elige tu propia cuenta como destino.
- Espera a que GitHub termine de copiar.
- Ya tienes tu propio fork del repositorio.
Deberías verYour browser is on your fork, and the header says "forked from abderrahim-lectures/python-data-analysis-course". -
Clona tu fork
Clonar descarga tu fork a tu ordenador para que puedas editar archivos con normalidad. Clona tu fork, no el original: no puedes hacer push al original.
- Abre una terminal en la carpeta donde guardas tus proyectos.
- Ejecuta el comando de clonado de abajo, sustituyendo TU-USUARIO.
- Entra en la carpeta nueva.
- Instala las dependencias.
Deberías verCloning into 'python-data-analysis-course'... added 400+ packages in 30sgit clone https://github.com/YOUR-USERNAME/python-data-analysis-course.git cd python-data-analysis-course npm install -
Crea una rama
Una rama mantiene tu trabajo separado de main. Una rama por proyecto, para que un revisor vea exactamente qué cambiaste y nadie quede bloqueado mientras se revisa.
- Elige un nombre corto de tu proyecto, en minúsculas y con guiones.
- Crea y cámbiate a la rama en un solo comando.
Deberías verSwitched to a new branch 'add-file-organizer'git checkout -b add-file-organizer -
Copia un proyecto como plantilla
Cada página de proyecto es un archivo markdown con el mismo esqueleto. Empieza por uno que ya funciona en lugar de un archivo vacío: tiene el frontmatter, un reto y un cuestionario con la forma correcta.
- Copia ai-agent.md al nombre de archivo de tu proyecto. El nombre del archivo se convierte en la URL.
Deberías versrc/content/projects/file-organizer.md is created and opens in your editor.cp src/content/projects/ai-agent.md src/content/projects/file-organizer.md -
Rellena el frontmatter
El frontmatter es el bloque entre las dos líneas --- de arriba. Cuatro campos son obligatorios: title, description, difficulty y author. Los tests rechazan un proyecto al que le falte cualquiera.
- Edita title: lo que muestra la tarjeta, unos 50 caracteres.
- Edita description: una frase de menos de 160 caracteres.
- Pon difficulty: beginner, intermediate o advanced.
- Pon author: tu id de colaborador del paso 9.
Deberías verA frontmatter like the example below. The two --- lines must be the very first and last lines of the block.Un frontmatter completo, copiado de un proyecto real:
--- title: "Build a File-Organizer Bot" description: "Sort a messy folder into category subfolders with a bot that plans before it moves." difficulty: "beginner" author: your-id ---Copia un proyecto existente y cámbialo. Los tests comprueban que cada proyecto tiene los campos obligatorios, así que uno que falte falla antes de que lo vea un revisor.
-
Escribe el cuerpo
El cuerpo es lo que un lector sigue de verdad. Todos los proyectos de este curso tienen la misma forma, para que los lectores sepan dónde mirar.
- Empieza con un encabezado # y una línea sobre lo que van a construir.
- Añade un párrafo de por qué importa.
- Añade una lista numerada Qué vas a hacer con 3-6 resultados.
- Divide la construcción en pasos, con comandos y salidas reales.
- Añade un reto con respuesta oculta en un bloque details.
- Añade un cuestionario corto.
Deberías verA page that reads like the other project pages: introduction, numbered outcomes, step-by-step build, challenge, quiz.El inicio del cuerpo de un proyecto real. Fíjate en que dice con qué termina el lector y luego numera los pasos:
# 📁 Build a File-Organizer Bot A folder you have been dumping things into for a year. You could sort it by hand, or write the thing that sorts it. ## 🎯 What you will do 1. Scan a folder and classify each file by extension. 2. Build a dry run: compute every move, print it, touch nothing. 3. Perform the moves, handling collisions instead of overwriting. -
Añade el código ejecutable (opcional)
Si tu proyecto tiene código que merece ejecutarse, dale una carpeta para que los lectores puedan ejecutarlo. Los proyectos que son sobre todo explicación pueden saltarse este paso.
- Crea examples/<tu-slug>/.
- Añade tu archivo de código.
- Añade un README.md explicando cómo ejecutarlo.
- Añade un pyproject.toml para que funcione uv run.
- Nothing here needs third-party packages unless the project genuinely requires them.
Deberías verexamples/file-organizer/README.md examples/file-organizer/organizer.py examples/file-organizer/pyproject.tomlmkdir -p examples/file-organizer # add README.md, organizer.py and pyproject.toml -
Acredítate
La página de colaboradores se construye desde un registro, no desde el historial de git, así que tu nombre aparece solo si lo añades. Esto también permite acreditar a estudiantes sin cuenta de GitHub.
- Abre src/lib/contributors.ts.
- Añade una entrada al array CONTRIBUTORS.
- Usa el mismo id que en el campo author.
- Guarda el archivo.
Deberías verYour entry in the array, exactly like the example below. The id is lowercase with hyphens and must match author exactly.Una entrada en src/lib/contributors.ts. El id es lo que debe coincidir con el campo author de tu proyecto:
export const CONTRIBUTORS: Contributor[] = [ { id: 'your-id', name: 'Your Name', github: 'your-handle', role: 'Wrote the file-organizer project', }, ]; -
Ejecuta las comprobaciones
Estas son las mismas comprobaciones que ejecuta CI. Ejecútalas antes de abrir la pull request para que un revisor vea una build en verde, no una lista de errores.
- npm run test comprueba el esquema del contenido, los enlaces y las traducciones.
- npx tsc --noEmit comprueba el TypeScript.
- npm run build construye todas las páginas, lo que detecta imports roos.
Deberías verTests 1743 passed (38 files). No TypeScript errors. Build complete with no failed pages.npm run test npx tsc --noEmit npm run build -
Haz commit y push
Un commit es un punto de guardado con un mensaje. Un push lo envía a tu fork en GitHub, donde la pull request puede verlo.
- Prepara los archivos que cambiaste.
- Haz commit con un mensaje corto.
- Empuja la rama a tu fork.
Deberías ver2 files changed, 45 insertions(+) To github.com:YOUR-USERNAME/python-data-analysis-course.gitgit add src/content/projects/file-organizer.md src/lib/contributors.ts git commit -m "content: add file-organizer" git push -u origin add-file-organizer -
Abre la pull request
Una pull request pide a un mantenedor que revise tu trabajo y lo fusione. Describe qué enseña el proyecto y para quién es; un revisor lee el contenido, no solo el diff.
- Ve a tu fork en GitHub; un aviso ofrece abrir una pull request.
- Pulsa Compare and pull request.
- Escribe un título y una descripción.
- Pulsa Create pull request.
Deberías verA pull request page showing your changes and the CI checks running.
Archivos que vas a tocar
-
src/content/projects/<your-slug>.mdObligatorioLa página del proyecto en sí. Campos del frontmatter: title, description, difficulty, tags y author (tu id de colaborador). Todo lo que va después del frontmatter es la lección que sigue quien lee.
-
examples/<your-slug>/OpcionalCódigo de acompañamiento que se puede ejecutar en local, si el proyecto tiene código. Los proyectos que enseñan un concepto sin construir una herramienta pueden omitirlo.
-
src/lib/contributors.tsSolo si eres nuevo en la páginaAñade una entrada con tu id, tu nombre y, si quieres, tu usuario de GitHub. Pon author: <tu-id> en la página de tu proyecto y aparecerá en la página de colaboradores.
Lo que hace que una pull request se mergee antes
- Enseña una cosa de principio a fin. Un proyecto que construye una herramienta pequeña con honestidad vale más que uno que toca cinco librerías.
- Mantén el código ejecutable. Quien lee debería poder copiar un paso y ejecutarlo, no solo leerlo.
- Escribe la sección de errores al final, a partir de los que cometiste tú mientras lo construías.
- No añadas una traducción salvo que hables el idioma de verdad. Con el inglés basta; el resto lo cubren los traductores.