PyDA Course

Contribuer

Ajouter un projet

Tous les projets concrets de ce site ont commencé comme un fichier markdown dans la pull request de quelqu'un. Cette page liste exactement quoi modifier, dans l'ordre, et les commandes pour vérifier votre travail avant de l'envoyer.

Schéma : les trois fichiers dont un nouveau projet a besoin. L’étape 1 est un fichier markdown obligatoire dans src/content/projects. L’étape 2 est un dossier examples facultatif. L’étape 3 est une entrée obligatoire dans src/lib/contributors.ts.
Les trois fichiers. Seul celui du milieu est facultatif.
  1. Vérifiez vos outils

    Avant tout, assurez-vous d’avoir ce dont le projet a besoin. Il vous faut Node 22 ou plus récent (le site se construit avec) et git. Si une commande ci-dessous n’affiche rien, cet outil manque.

    1. node --version
    2. git --version
    3. Vérifiez la version de Node et de git avec les commandes ci-dessous.
    4. Si Node est antérieur à 22, installez le LTS actuel depuis nodejs.org.
    Vous devriez voir
    node --version   # v22.x or newer
    git --version    # any recent version
  2. Forkez le dépôt

    Un fork est votre propre copie du dépôt, sur votre compte GitHub. Vous travaillez là, donc rien de ce que vous faites ne peut affecter le site en ligne.

    1. Ouvrez github.com/abderrahim-lectures/python-data-analysis-course.
    2. Cliquez sur le bouton Fork en haut à droite.
    3. Choisissez votre compte comme destination.
    4. Attendez que GitHub termine la copie.
    5. Vous avez maintenant votre propre fork.
    Vous devriez voir
    Your browser is on your fork, and the header says "forked from abderrahim-lectures/python-data-analysis-course".
  3. Clonez votre fork

    Cloner télécharge votre fork sur votre ordinateur pour que vous puissiez modifier les fichiers normalement. Clonez votre fork, pas l’original : vous ne pouvez pas pousser vers l’original.

    1. Ouvrez un terminal dans le dossier de vos projets.
    2. Lancez la commande de clonage ci-dessous en remplaçant VOTRE-UTILISATEUR.
    3. Entrez dans le nouveau dossier.
    4. Installez les dépendances.
    Vous devriez voir
    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. Créez une branche

    Une branche garde votre travail séparé de main. Une branche par projet, pour qu’un relecteur voie exactement ce que vous avez changé et que personne ne soit bloqué pendant la relecture.

    1. Choisissez un nom court, en minuscules avec des tirets.
    2. Créez la branche et basculez dessus en une commande.
    Vous devriez voir
    Switched to a new branch 'add-file-organizer'
    git checkout -b add-file-organizer
  5. Copiez un projet comme modèle

    Chaque page de projet est un fichier markdown avec le même squelette. Partez d’un projet qui fonctionne déjà plutôt que d’un fichier vide : il a le frontmatter, un défi et un quiz dans la bonne forme.

    1. Copiez ai-agent.md vers le nom de fichier de votre projet. Le nom devient l’URL.
    Vous devriez voir
    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. Remplissez le frontmatter

    Le frontmatter est le bloc entre les deux lignes --- en haut. Quatre champs sont obligatoires : title, description, difficulty et author. Les tests rejettent un projet auquel il en manque un.

    1. Modifiez title : ce que la carte affiche, une cinquantaine de caractères.
    2. Modifiez description : une phrase de moins de 160 caractères.
    3. Réglez difficulty : beginner, intermediate ou advanced.
    4. Réglez author : votre id de l’étape 9.
    Vous devriez voir
    A frontmatter like the example below. The two --- lines must be the very first and last lines of the block.

    Un frontmatter complet, copié d’un vrai projet :

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

    Copiez un projet existant et modifiez-le. Les tests vérifient que chaque projet a les champs obligatoires, donc un champ manquant échoue avant qu’un relecteur ne le voie.

  7. Écrivez le corps

    Le corps est ce qu’un lecteur suit vraiment. Tous les projets de ce cours ont la même forme, pour que les lecteurs sachent où regarder.

    1. Commencez par un titre # et une ligne sur ce qu’ils vont construire.
    2. Ajoutez un paragraphe pourquoi cela compte.
    3. Ajoutez une liste numérotée de 3 à 6 résultats.
    4. Découpez en étapes avec de vraies commandes et sorties.
    5. Ajoutez un défi avec réponse masquée dans un bloc details.
    6. Ajoutez un court quiz.
    Vous devriez voir
    A page that reads like the other project pages: introduction, numbered outcomes, step-by-step build, challenge, quiz.

    Le début du corps d’un vrai projet. Remarquez qu’il annonce ce que le lecteur obtient, puis numérote les étapes :

    # 📁 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. Ajoutez le code exécutable (facultatif)

    Si votre projet a du code qui mérite d’être exécuté, donnez-lui un dossier pour que les lecteurs puissent le lancer. Les projets surtout explicatifs peuvent sauter cette étape.

    1. Créez examples/<votre-slug>/.
    2. Ajoutez votre fichier de code.
    3. Ajoutez un README.md expliquant comment le lancer.
    4. Ajoutez un pyproject.toml pour que uv run fonctionne.
    5. Nothing here needs third-party packages unless the project genuinely requires them.
    Vous devriez voir
    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. Créditez-vous

    La page des contributeurs est construite à partir d’un registre, pas de l’historique git, donc votre nom n’apparaît que si vous l’ajoutez. Cela permet aussi de créditer des étudiants sans compte GitHub.

    1. Ouvrez src/lib/contributors.ts.
    2. Ajoutez une entrée au tableau CONTRIBUTORS.
    3. Utilisez le même id que dans author.
    4. Enregistrez le fichier.
    Vous devriez voir
    Your entry in the array, exactly like the example below. The id is lowercase with hyphens and must match author exactly.

    Une entrée dans src/lib/contributors.ts. L’id est ce que le champ author de votre projet doit reprendre :

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

    Ce sont les mêmes vérifications que la CI. Lancez-les avant d’ouvrir la pull request pour qu’un relecteur voie une build verte, pas une liste d’erreurs.

    1. npm run test vérifie le schéma du contenu, les liens et les traductions.
    2. npx tsc --noEmit vérifie le TypeScript.
    3. npm run build construit toutes les pages, ce qui attrape les imports cassés.
    Vous devriez voir
    Tests 1743 passed (38 files). No TypeScript errors. Build complete with no failed pages.
    npm run test
    npx tsc --noEmit
    npm run build
  11. Commitez et poussez

    Un commit est un point de sauvegarde avec un message. Un push l’envoie vers votre fork sur GitHub, où la pull request peut le voir.

    1. Préparez les fichiers modifiés.
    2. Commitez avec un court message.
    3. Poussez la branche vers votre fork.
    Vous devriez voir
    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. Ouvrez la pull request

    Une pull request demande à un mainteneur de relire votre travail et de le fusionner. Décrivez ce que le projet enseigne et à qui il s’adresse ; un relecteur lit le contenu, pas seulement le diff.

    1. Allez sur votre fork ; une bannière propose d’ouvrir une pull request.
    2. Cliquez sur Compare and pull request.
    3. Écrivez un titre et une description.
    4. Cliquez sur Create pull request.
    Vous devriez voir
    A pull request page showing your changes and the CI checks running.
Schéma : le trajet d’une contribution. Forkez le dépôt, clonez-le, créez une branche, commitez et poussez, puis ouvrez une pull request. La fusion dans main publie le site automatiquement.
Où chaque commande s’exécute. Les étapes deux à quatre se font sur votre machine.

Les fichiers que vous allez toucher

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

    La page du projet elle-même. Champs du frontmatter : title, description, difficulty, tags et author (votre identifiant de contributeur). Tout ce qui suit le frontmatter est la leçon que suit le lecteur.

  • examples/<your-slug>/ Facultatif

    Du code d'accompagnement exécutable en local, si le projet contient du code. Les projets qui enseignent un concept sans construire d'outil peuvent s'en passer.

  • src/lib/contributors.ts Seulement si vous êtes nouveau sur la page

    Ajoutez une entrée avec votre identifiant, votre nom et, si vous le souhaitez, votre compte GitHub. Renseignez author: <votre-id> dans la page du projet pour apparaître sur la page des contributeurs.

Ce qui fait merger une pull request plus vite

  • Enseignez une seule chose de bout en bout. Un projet qui construit un petit outil honnêtement vaut mieux qu'un projet qui effleure cinq bibliothèques.
  • Gardez le code exécutable. Un lecteur doit pouvoir copier une étape et la lancer, pas seulement la lire.
  • Écrivez la section des pièges en dernier, à partir des erreurs que vous avez réellement faites en le construisant.
  • N'ajoutez pas de traduction vous-même sauf si vous parlez vraiment la langue. L'anglais suffit ; les traducteurs s'occupent du reste.