PyDA Course

Contributing

Add a project

Every real-world project here started as one markdown file in someone's pull request. This page lists exactly what to change, in order, plus the commands to check your work before you submit it.

Diagram: the three files a new project needs. Step 1 is a required markdown file in src/content/projects. Step 2 is an optional examples folder. Step 3 is a required entry in src/lib/contributors.ts.
The three files. Only the middle one is optional.
  1. Check your tools

    Before anything else, make sure you have what the project needs. You need Node 22 or newer (the site builds with it) and git. If a command below prints nothing, that tool is missing.

    1. node --version
    2. git --version
    3. If Node is older than 22, install the current LTS from nodejs.org before continuing.
    You should see
    node --version   # v22.x or newer
    git --version    # any recent version
  2. Fork the repository

    A fork is your own copy of the repository, on your GitHub account. You work there, so nothing you do can affect the live site.

    1. Open github.com/abderrahim-lectures/python-data-analysis-course.
    2. Click the Fork button at the top right.
    3. Choose your own account as the destination.
    4. Wait for GitHub to finish copying (a few seconds).
    5. You now have github.com/YOUR-USERNAME/python-data-analysis-course.
    You should see
    Your browser is on your fork, and the header says "forked from abderrahim-lectures/python-data-analysis-course".
  3. Clone your fork

    Cloning downloads your fork to your computer so you can edit files normally. Clone your fork, not the original: you cannot push to the original.

    1. Open a terminal in the folder where you keep projects.
    2. Run the clone command below, replacing YOUR-USERNAME.
    3. Move into the new folder.
    4. Install the dependencies.
    You should see
    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. Create a branch

    A branch keeps your work separate from main. One branch per project, so a reviewer can see exactly what you changed and nobody else is blocked while it is reviewed.

    1. Pick a short name from your project, lowercase with hyphens.
    2. Create and switch to it in one command.
    You should see
    Switched to a new branch 'add-file-organizer'
    git checkout -b add-file-organizer
  5. Copy a project as your template

    Every project page is a markdown file with the same skeleton. Start from one that already works rather than an empty file: it has the frontmatter, a challenge and a quiz in the right shape.

    1. Copy ai-agent.md to your project's filename. The filename becomes the URL, so name it what you want the page called.
    You should see
    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. Fill in the frontmatter

    The frontmatter is the block between the two --- lines at the top. Four fields are required: title, description, difficulty and author. The tests reject a project missing any of them.

    1. Edit title: what the card shows. Keep it under about 50 characters.
    2. Edit description: one sentence, under about 160 characters, saying what the reader builds.
    3. Set difficulty: exactly beginner, intermediate or advanced.
    4. Set author: your contributor id from step 9. A placeholder is fine for now.
    You should see
    A frontmatter like the example below. The two --- lines must be the very first and last lines of the block.

    A complete frontmatter, copied from a real project:

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

    Copy an existing project and change it. The tests check that every project has the required fields, so a missing one fails before a reviewer sees it.

  7. Write the body

    The body is what a reader actually follows. Every project in this course has the same shape, so readers know where to look.

    1. Start with a # heading and one line on what they will build.
    2. Add a why-this-matters paragraph: the problem before the solution.
    3. Add a numbered What you will do list of 3-6 outcomes.
    4. Break the build into steps, each with a real command and its real output.
    5. Add one challenge with a hidden answer (a <details> block).
    6. Add a short quiz (the <div class="quiz"> block).
    You should see
    A page that reads like the other project pages: introduction, numbered outcomes, step-by-step build, challenge, quiz.

    The opening of a real project body. Note that it says what the reader ends up with, then numbers the steps:

    # 📁 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. Add the runnable code (optional)

    If your project has code worth running, give it a folder so readers can run it themselves. Projects that are mostly explanation can skip this step entirely.

    1. Create examples/<your-slug>/.
    2. Add your code file, for example organizer.py.
    3. Add a README.md explaining how to run it.
    4. Add a pyproject.toml so `uv run` works.
    5. Nothing here needs third-party packages unless the project genuinely requires them.
    You should see
    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. Credit yourself

    The contributors page is built from a registry, not from git history, so your name appears only if you add it. This also lets students without a GitHub account be credited.

    1. Open src/lib/contributors.ts.
    2. Add one entry to the CONTRIBUTORS array.
    3. Use the same id you put in your project's author field.
    4. Save the file.
    You should see
    Your entry in the array, exactly like the example below. The id is lowercase with hyphens and must match author exactly.

    One entry in src/lib/contributors.ts. The id is what your project’s author field must match:

    export const CONTRIBUTORS: Contributor[] = [
      {
        id: 'your-id',
        name: 'Your Name',
        github: 'your-handle',
        role: 'Wrote the file-organizer project',
      },
    ];
  10. Run the checks

    These are the same checks CI runs. Run them before opening the pull request so a reviewer sees a green build, not a list of errors.

    1. npm run test checks the content schema, links and translations.
    2. npx tsc --noEmit checks the TypeScript.
    3. npm run build builds every page, which catches broken imports.
    You should see
    Tests 1743 passed (38 files). No TypeScript errors. Build complete with no failed pages.
    npm run test
    npx tsc --noEmit
    npm run build
  11. Commit and push

    A commit is a save point with a message. A push sends it to your fork on GitHub, where the pull request can see it.

    1. Stage the files you changed.
    2. Commit with a short message describing what you added.
    3. Push the branch to your fork.
    You should see
    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. Open the pull request

    A pull request asks a maintainer to review your work and merge it. Describe what the project teaches and who it is for; a reviewer reads the content, not just the diff.

    1. Go to your fork on GitHub; a banner offers to open a pull request.
    2. Click Compare & pull request.
    3. Write a title and a description using the template below.
    4. Click Create pull request.
    You should see
    A pull request page showing your changes and the CI checks running.
Diagram: how a contribution travels. Fork the repository, clone it, create a branch, commit and push, then open a pull request. Merging to main publishes the site automatically.
Where each command happens. You run steps two to four on your own machine.

Files you will touch

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

    The project page itself. Frontmatter fields: title, description, difficulty, tags, and author (your contributor id). Everything after the frontmatter is the lesson the reader follows.

  • examples/<your-slug>/ Optional

    Companion code that a reader can run locally, if the project has code. Projects that teach a concept rather than build a tool can skip it.

  • src/lib/contributors.ts Only if you are new to the page

    Add an entry with your id, display name, and optionally your GitHub handle. Set author: <your-id> on your project page and it appears on the contributors page.

Things that get a pull request merged faster

  • Teach one thing end to end. A project that builds one small tool honestly beats one that touches five libraries.
  • Keep the code runnable. A reader should be able to copy a step and run it, not just read it.
  • Write the pitfalls section last, from the mistakes you actually made while building it.
  • Do not add a translation yourself unless you actually speak the language. English is enough; translators pick up the rest.