PyDA Course

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.

Diagrama: los tres archivos que necesita un proyecto nuevo. El paso 1 es un archivo markdown obligatorio en src/content/projects. El paso 2 es una carpeta examples opcional. El paso 3 es una entrada obligatoria en src/lib/contributors.ts.
Los tres archivos. Solo el del medio es opcional.
  1. 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.

    1. node --version
    2. git --version
    3. Comprueba la versión de Node y de git con los comandos de abajo.
    4. Si Node es anterior a 22, instala el LTS actual desde nodejs.org antes de continuar.
    Deberías ver
    node --version   # v22.x or newer
    git --version    # any recent version
  2. 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.

    1. Abre github.com/abderrahim-lectures/python-data-analysis-course.
    2. Pulsa el botón Fork arriba a la derecha.
    3. Elige tu propia cuenta como destino.
    4. Espera a que GitHub termine de copiar.
    5. Ya tienes tu propio fork del repositorio.
    Deberías ver
    Your browser is on your fork, and the header says "forked from abderrahim-lectures/python-data-analysis-course".
  3. 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.

    1. Abre una terminal en la carpeta donde guardas tus proyectos.
    2. Ejecuta el comando de clonado de abajo, sustituyendo TU-USUARIO.
    3. Entra en la carpeta nueva.
    4. Instala las dependencias.
    Deberías ver
    Cloning into 'python-data-analysis-course'...
    added 400+ packages in 30s
    git clone https://github.com/YOUR-USERNAME/python-data-analysis-course.git
    cd python-data-analysis-course
    npm install
  4. 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.

    1. Elige un nombre corto de tu proyecto, en minúsculas y con guiones.
    2. Crea y cámbiate a la rama en un solo comando.
    Deberías ver
    Switched to a new branch 'add-file-organizer'
    git checkout -b add-file-organizer
  5. 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.

    1. Copia ai-agent.md al nombre de archivo de tu proyecto. El nombre del archivo se convierte en la URL.
    Deberías ver
    src/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
  6. 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.

    1. Edita title: lo que muestra la tarjeta, unos 50 caracteres.
    2. Edita description: una frase de menos de 160 caracteres.
    3. Pon difficulty: beginner, intermediate o advanced.
    4. Pon author: tu id de colaborador del paso 9.
    Deberías ver
    A 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.

  7. 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.

    1. Empieza con un encabezado # y una línea sobre lo que van a construir.
    2. Añade un párrafo de por qué importa.
    3. Añade una lista numerada Qué vas a hacer con 3-6 resultados.
    4. Divide la construcción en pasos, con comandos y salidas reales.
    5. Añade un reto con respuesta oculta en un bloque details.
    6. Añade un cuestionario corto.
    Deberías ver
    A 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.
  8. 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.

    1. Crea examples/<tu-slug>/.
    2. Añade tu archivo de código.
    3. Añade un README.md explicando cómo ejecutarlo.
    4. Añade un pyproject.toml para que funcione uv run.
    5. Nothing here needs third-party packages unless the project genuinely requires them.
    Deberías ver
    examples/file-organizer/README.md
      examples/file-organizer/organizer.py
      examples/file-organizer/pyproject.toml
    mkdir -p examples/file-organizer
    # add README.md, organizer.py and pyproject.toml
  9. 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.

    1. Abre src/lib/contributors.ts.
    2. Añade una entrada al array CONTRIBUTORS.
    3. Usa el mismo id que en el campo author.
    4. Guarda el archivo.
    Deberías ver
    Your 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',
      },
    ];
  10. 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.

    1. npm run test comprueba el esquema del contenido, los enlaces y las traducciones.
    2. npx tsc --noEmit comprueba el TypeScript.
    3. npm run build construye todas las páginas, lo que detecta imports roos.
    Deberías ver
    Tests 1743 passed (38 files). No TypeScript errors. Build complete with no failed pages.
    npm run test
    npx tsc --noEmit
    npm run build
  11. 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.

    1. Prepara los archivos que cambiaste.
    2. Haz commit con un mensaje corto.
    3. Empuja la rama a tu fork.
    Deberías ver
    2 files changed, 45 insertions(+)
    To github.com:YOUR-USERNAME/python-data-analysis-course.git
    git 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
  12. 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.

    1. Ve a tu fork en GitHub; un aviso ofrece abrir una pull request.
    2. Pulsa Compare and pull request.
    3. Escribe un título y una descripción.
    4. Pulsa Create pull request.
    Deberías ver
    A pull request page showing your changes and the CI checks running.
Diagrama: cómo viaja una contribución. Haz un fork del repositorio, clónalo, crea una rama, haz commit y push, y abre una pull request. Al fusionar en main el sitio se publica automáticamente.
Dónde ocurre cada comando. Los pasos dos a cuatro se ejecutan en tu máquina.

Archivos que vas a tocar

  • src/content/projects/<your-slug>.md Obligatorio

    La 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>/ Opcional

    Có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.ts Solo si eres nuevo en la página

    Añ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.