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.
-
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.
- node --version
- git --version
- Vérifiez la version de Node et de git avec les commandes ci-dessous.
- Si Node est antérieur à 22, installez le LTS actuel depuis nodejs.org.
Vous devriez voirnode --version # v22.x or newer git --version # any recent version -
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.
- Ouvrez github.com/abderrahim-lectures/python-data-analysis-course.
- Cliquez sur le bouton Fork en haut à droite.
- Choisissez votre compte comme destination.
- Attendez que GitHub termine la copie.
- Vous avez maintenant votre propre fork.
Vous devriez voirYour browser is on your fork, and the header says "forked from abderrahim-lectures/python-data-analysis-course". -
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.
- Ouvrez un terminal dans le dossier de vos projets.
- Lancez la commande de clonage ci-dessous en remplaçant VOTRE-UTILISATEUR.
- Entrez dans le nouveau dossier.
- Installez les dépendances.
Vous devriez voirCloning 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 -
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.
- Choisissez un nom court, en minuscules avec des tirets.
- Créez la branche et basculez dessus en une commande.
Vous devriez voirSwitched to a new branch 'add-file-organizer'git checkout -b add-file-organizer -
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.
- Copiez ai-agent.md vers le nom de fichier de votre projet. Le nom devient l’URL.
Vous devriez voirsrc/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 -
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.
- Modifiez title : ce que la carte affiche, une cinquantaine de caractères.
- Modifiez description : une phrase de moins de 160 caractères.
- Réglez difficulty : beginner, intermediate ou advanced.
- Réglez author : votre id de l’étape 9.
Vous devriez voirA 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.
-
É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.
- Commencez par un titre # et une ligne sur ce qu’ils vont construire.
- Ajoutez un paragraphe pourquoi cela compte.
- Ajoutez une liste numérotée de 3 à 6 résultats.
- Découpez en étapes avec de vraies commandes et sorties.
- Ajoutez un défi avec réponse masquée dans un bloc details.
- Ajoutez un court quiz.
Vous devriez voirA 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. -
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.
- Créez examples/<votre-slug>/.
- Ajoutez votre fichier de code.
- Ajoutez un README.md expliquant comment le lancer.
- Ajoutez un pyproject.toml pour que uv run fonctionne.
- Nothing here needs third-party packages unless the project genuinely requires them.
Vous devriez voirexamples/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 -
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.
- Ouvrez src/lib/contributors.ts.
- Ajoutez une entrée au tableau CONTRIBUTORS.
- Utilisez le même id que dans author.
- Enregistrez le fichier.
Vous devriez voirYour 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', }, ]; -
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.
- npm run test vérifie le schéma du contenu, les liens et les traductions.
- npx tsc --noEmit vérifie le TypeScript.
- npm run build construit toutes les pages, ce qui attrape les imports cassés.
Vous devriez voirTests 1743 passed (38 files). No TypeScript errors. Build complete with no failed pages.npm run test npx tsc --noEmit npm run build -
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.
- Préparez les fichiers modifiés.
- Commitez avec un court message.
- Poussez la branche vers votre fork.
Vous devriez voir2 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 -
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.
- Allez sur votre fork ; une bannière propose d’ouvrir une pull request.
- Cliquez sur Compare and pull request.
- Écrivez un titre et une description.
- Cliquez sur Create pull request.
Vous devriez voirA pull request page showing your changes and the CI checks running.
Les fichiers que vous allez toucher
-
src/content/projects/<your-slug>.mdObligatoireLa 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>/FacultatifDu 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.tsSeulement si vous êtes nouveau sur la pageAjoutez 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.