Aller au contenu
English

Comprendre le code par vous-même

  • Leçon 15
  • 45 min
  • Module 5 : Livrer un travail facile à maintenir

Où nous en sommes

Dans les deux dernières leçons, nous avons gardé la modification ciblée et documenté ses décisions avec des preuves. Il reste une étape avant la révision : un assistant a écrit une grande partie du code, mais nous répondons de chaque ligne. Dans cette leçon, nous expliquons sans aide chaque ligne qui change le comportement, montrons quel test la protège et ouvrons une demande de tirage qu'un réviseur peut vérifier seul, comme le cuisinier qui sert le plat.

Ce que vous saurez faire

Avant de demander une révision, expliquez sans aide chaque ligne qui change le comportement. Montrez quel test protège chaque ligne. Ouvrez une demande de tirage qu’un réviseur peut vérifier seul. Nommez les décisions qu’une personne doit encore prendre.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 45 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet ~/projects/ticket-cleaner-assist après la dernière leçon, avec son environnement actif. python -m pytest affiche 42 passed (42 tests réussis), et git status --short n’affiche rien.
  • main contient seulement le point de départ du cours. Vérifiez-le : git diff --stat main...feature/category-option -- ticket_cleaner/ se termine par 3 files changed, 34 insertions(+), 7 deletions(-) (3 fichiers modifiés, 34 ajouts, 7 suppressions). Sinon, suivez les étapes de réinitialisation sous Vérification du module.
  • Environ 40 Mo d’espace libre pour une deuxième copie du projet avec son propre environnement.
  • Aucun compte, aucun site Web et aucun paiement. Le dépôt distant est un dossier sur votre ordinateur.

Au restaurant, une personne demande : « Y a-t-il des noix dans cette sauce? » Un aide a préparé la sauce, pas le cuisinier. « Je ne l’ai pas faite » ne donne pas une réponse utile à cette personne. Le cuisinier qui sert le plat répond de chaque ingrédient. Un cuisinier prudent sait donc ce que contient l’assiette avant qu’elle quitte la cuisine.

Une demande de tirage, c’est l’assiette qui quitte la cuisine. L’assistant était l’aide.

Votre branche contient tout le changement de ce cours : l’option, la correction, le réusinage et les documents. Les 42 tests passent. Tomás lit le résultat :

« Quarante-deux tests réussis. Qu’est-ce qu’il reste à expliquer? Ouvrez la demande de tirage. »

Voici un point qu’aucun test ni aucune tâche ne mentionnait. Produisez le rapport pending (en attente) du fichier d’exemple sur main, puis sur votre branche :

Fenêtre de terminal
git switch main
python -m ticket_cleaner data/tickets.csv --status pending
git switch feature/category-option
python -m ticket_cleaner data/tickets.csv --status pending

Ouvrez reports/summary.json après chaque exécution. Voici les résultats de l’auteur :

by_category of the pending report
main: {"LOGIN": 1, "billing": 1}
feature/category-option: {"billing": 1, "login": 1}

Le fichier d’exemple contient un billet de soutien enregistré sous LOGIN (T-1010, ligne 11 de data/tickets.csv). La correction du module 4 a changé la façon d’enregistrer chaque catégorie. Ce rapport a donc changé aussi. C’est normal : la correction du bogue fait son travail. Mais l’équipe de Grace pourrait comparer le rapport de ce mois avec celui du mois dernier. Une ligne LOGIN qui disparaît semblera être un billet perdu, à moins qu’on les prévienne.

Le test de référence de base ne l’a pas détecté, car il fixe seulement le rapport open (ouvert) par défaut. Donc, « les tests passent » ne vous l’a pas révélé. Il fallait lire la ligne et se demander ce qu’elle touche d’autre.

Comprendre le code par vous-même signifie pouvoir expliquer votre changement final sans l’assistant, ligne par ligne, à un réviseur qui le demande. Toutes les lignes ne demandent pas la même attention. Une ligne importante change le comportement, un contrat, les données enregistrées ou la sécurité. Par exemple : une condition, une valeur par défaut, une clé du rapport ou une règle de nettoyage. Une ligne vide, une chaîne de documentation ou un appel remis en forme n’est pas une ligne importante. Vous la lisez quand même.

Pour chaque ligne importante, vous pouvez répondre à quatre questions :

  1. Que fait-elle, avec une entrée concrète?
  2. Pourquoi est-elle là : quelle exigence ou quel bogue la rend nécessaire?
  3. Quel test échoue sans elle?
  4. Que touche-t-elle d’autre?

Les deux premières réponses vont dans un tableau de traçabilité : chaque exigence, le changement qui y répond et la preuve. Vous avez vu sa première moitié dans Problème et critères d’acceptation. La demande de tirage le complète avec les différences et les tests.

Un tableau à trois colonnes : exigence, changement et preuve. 1, compter seulement les catégories choisies : report.py build_summary avec categories; test_one_category. 2, l'option peut être fournie plusieurs fois : cli.py action append; test_a_ticket_in_any_chosen_category_counts et test_report_for_some_categories. 3, les majuscules et les espaces ne comptent pas : report.py clean_category du nom; test_category_name_ignores_capital_letters_and_spaces. 4, clé categories seulement avec l'option : report.py, if chosen is not None; test_categories_key_only_with_the_option et tests/test_baseline.py. 5, comptes du fichier entier inchangés : report.py filtre après les totaux; test_categories_do_not_change_the_whole_file_counts. 6, une catégorie inconnue n'est pas une erreur : aucun code nécessaire; test_unknown_category_selects_nothing. 7, l'aide et le README décrivent l'option : aide de cli.py et README.md; test_help_describes_the_category_option et tests/test_readme.py. Bogue, une ligne par équipe : parsing.py clean_category nettoie d'abord; test_capital_letters_do_not_make_a_new_category, qui échouait avant la correction, et test_web_form_export_has_one_line_per_team. Pied de page : une ligne sans test est une affirmation; un test sans ligne est un changement que personne n'a demandé.
Exigence → changement → preuve, comme dans docs/pull-request.md. La branche entière compte 16 fichiers, +536 −9, mais le code compte trois fichiers, +34 −7.
Description textuelle du diagramme
Exigence Changement (fichier) Preuve (test)
1. Compter seulement les catégories choisies report.py : build_summary(..., categories) test_one_category
2. L’option peut être fournie plusieurs fois cli.py : action="append" test_a_ticket_in_any_chosen_category_counts, test_report_for_some_categories
3. Les majuscules et les espaces ne comptent pas report.py : clean_category(name) test_category_name_ignores_capital_letters_and_spaces
4. Clé categories seulement avec l’option report.py : if chosen is not None test_categories_key_only_with_the_option, tests/test_baseline.py
5. Comptes du fichier entier inchangés report.py : filtre après les totaux test_categories_do_not_change_the_whole_file_counts
6. Une catégorie inconnue n’est pas une erreur (aucun code nécessaire) test_unknown_category_selects_nothing
7. L’aide et le README décrivent l’option Aide de cli.py, README.md test_help_describes_the_category_option, tests/test_readme.py
Bogue : une ligne par équipe parsing.py : clean_category nettoie d’abord test_capital_letters_do_not_make_a_new_category (il échouait avant la correction), test_web_form_export_has_one_line_per_team

Comment savoir si un test protège vraiment une ligne? Changez la ligne volontairement, lancez les tests, puis rétablissez-la. Si aucun test n’échoue, la ligne n’a pas de protection ou ne fait rien. Les spécialistes des tests appellent une forme systématique de cette méthode les tests par mutation. À la main, pour quelques lignes, cela prend quelques minutes.

Prenez l’exigence 2. Dans ticket_cleaner/cli.py, supprimez une ligne de l’option --category, puis enregistrez :

ticket_cleaner/cli.py (changed on purpose)
parser.add_argument(
"--category",
action="append",
metavar="NAME",

Prédisez quels tests échoueront. Puis lancez-les :

Fenêtre de terminal
python -m pytest
Output (the end)
FAILED tests/test_cli.py::test_report_for_some_categories - ...
========================= 1 failed, 41 passed in 0.05s =========================

Un seul test. Sans action="append", args.category contient un seul texte plutôt qu’une liste, et le dernier --category l’emporte. Les tests unitaires de test_report.py appellent build_summary() avec une liste. Ils ne peuvent donc pas le voir. Seul le test qui exécute la commande entière le peut. Rétablissez la ligne et vérifiez que rien d’autre n’a changé :

Fenêtre de terminal
git restore ticket_cleaner/cli.py
git status --short

git status --short n’affiche rien. L’auteur a fait la même chose pour six lignes importantes :

Un tableau de six lignes changées volontairement, des tests qui échouent et du résultat. parsing.py, la correction, text égale clean_text de value remplacé par str de value avec strip : test_capital_letters_do_not_make_a_new_category, l'exportation de Grace, 3 cas de nettoyage, Sign-in et 4 tests de l'option; 10 échecs, 32 réussites. report.py, clean_category de name remplacé par name : majuscules et espaces, la clé categories, Sign-in et test_report_for_some_categories; 4 échecs, 38 réussites. report.py, clean_category de name remplacé par name strip lower : seulement test_web_form_names_work_in_the_category_option, le test de ce module; 1 échec, 41 réussites, en orange. report.py, la clé categories dans chaque rapport : tests/test_baseline.py et test_categories_key_only_with_the_option; 2 échecs, 40 réussites. report.py, valid_records égale la longueur de la sélection : tests/test_baseline.py, test_report_for_some_categories et 2 tests du fichier entier; 4 échecs, 38 réussites. cli.py sans action append : test_report_for_some_categories; 1 échec, 41 réussites, en orange. Pied de page : chaque ligne importante a un test qui échoue sans elle; pour deux lignes, il n'y a qu'un test, ne le supprimez pas.
Six lignes importantes, chacune changée volontairement à la fin du module. Toutes ont une protection; deux en ont exactement une.
Description textuelle du diagramme
Ligne changée volontairement Résultat
parsing.py : text = clean_text(value) → str(value).strip() (annuler la correction) 10 échecs, 32 réussites
report.py : clean_category(name) → name 4 échecs, 38 réussites
report.py : clean_category(name) → name.strip().lower() (la règle du module 4) 1 échec, 41 réussites : seulement test_web_form_names_work_in_the_category_option
report.py : la clé categories dans chaque rapport 2 échecs, 40 réussites : le test de référence de base et test_categories_key_only_with_the_option
report.py : "valid_records": len(selected) 4 échecs, 38 réussites
cli.py : sans action="append" 1 échec, 41 réussites : seulement test_report_for_some_categories

Voici la tâche pratique du module : soumettre la fonctionnalité et la correction du défaut dans une demande de tirage facile à réviser. Comme dans le cours sur Git, c’est une simulation locale. Le dépôt distant est un dépôt nu dans un dossier. Vous jouez les deux rôles : Amira, qui ouvre la demande, et Kwame, qui la révise.

  1. Regardez tout le changement d’un coup. Deux points listent les commits (changements enregistrés) de la branche. Trois points montrent les changements depuis la création de la branche :

    Fenêtre de terminal
    git log --oneline main..feature/category-option
    git diff --stat main...feature/category-option -- ticket_cleaner/
    Output (the author's run)
    51b4ddf Document the cleaning rule, the limitations and the decisions
    23d515b Clean the --category names with the same rule as the tickets
    b52a2f9 Copy the snapshot end-of-m04
    ticket_cleaner/cli.py | 8 +++++++-
    ticket_cleaner/parsing.py | 9 ++++++---
    ticket_cleaner/report.py | 24 +++++++++++++++++++++---
    3 files changed, 34 insertions(+), 7 deletions(-)

    L’auteur a regroupé les modules 1 à 4 dans un seul commit, comme le font les étapes de réinitialisation. Votre liste contient onze commits : neuf des modules 1 à 4, et deux de ce module. La ligne --stat est la même.

  2. Lisez la partie code, avec le tableau ci-dessus à côté :

    Fenêtre de terminal
    git diff main...feature/category-option -- ticket_cleaner/

    Pour chaque ligne modifiée, dites à voix haute : ce qu’elle fait, pourquoi, quel test la protège et ce qu’elle touche d’autre. Les lignes 31 à 36 de cli.py ajoutent l’option. La ligne 71 la transmet. Les lignes 23 et 24 de parsing.py sont la correction. Dans report.py, la ligne 1 importe l’unique règle de nettoyage. Les lignes 38 à 41 choisissent et filtrent. Les lignes 50 et 51 ajoutent la clé categories. Le reste contient des chaînes de documentation et la nouvelle signature.

  3. Brisez une ligne volontairement, comme dans le petit exemple. Choisissez une ligne du tableau, mais pas celle de l’exemple. Prédisez le résultat, lancez python -m pytest, puis rétablissez le fichier avec git restore. Notez la ligne et le test qui a détecté le changement. Vous les utiliserez dans la vérification de fin de module.

  4. Rédigez la description de la demande de tirage. Elle se trouve dans le projet, sous docs/pull-request.md, pour accompagner la branche. Copiez-la depuis l’instantané, puis comparez chaque ligne à vos propres exécutions :

    Fenêtre de terminal
    cp ../nextia-learning-labs/C15/snapshots/end-of-m05/docs/pull-request.md docs/

    Elle contient les parties du cours sur Git, et trois autres : le tableau, l’utilisation d’un assistant et les points à réviser. Le texte complet se trouve après ces étapes.

  5. Lancez les vérifications promises dans la description, puis enregistrez-la dans un commit :

    Fenêtre de terminal
    python -m pytest
    ruff check .
    ruff format --check .
    python -m ticket_cleaner data/web-form-export.csv --category Sign-in
    git add docs/pull-request.md
    git commit -m "Describe the pull request"
    Sortie (extrait)
    ============================== 42 passed in 0.04s ==============================
    All checks passed!
    24 files already formatted
    [feature/category-option bd7c066] Describe the pull request
    1 file changed, 45 insertions(+)
    create mode 100644 docs/pull-request.md

    Le rapport de la commande Sign-in (connexion) contient "by_category": {"login": 4}.

  6. Créez le dépôt distant à côté du projet. Utilisez un nouveau nom : team-remote.git du cours sur Git contient ticket-notes, un autre projet.

    Fenêtre de terminal
    cd ..
    git init --bare ticket-cleaner-remote.git
    cd ticket-cleaner-assist
    git remote add origin ../ticket-cleaner-remote.git
    Sortie
    Initialized empty Git repository in ~/projects/ticket-cleaner-remote.git/

    Votre sortie montre le chemin complet de votre dossier.

  7. Poussez les deux branches. La cible main doit exister sur le dépôt distant pour permettre au réviseur de comparer :

    Fenêtre de terminal
    git push -u origin main
    git push -u origin feature/category-option
    Sortie
    To ../ticket-cleaner-remote.git
    * [new branch] main -> main
    branch 'main' set up to track 'origin/main'.
    To ../ticket-cleaner-remote.git
    * [new branch] feature/category-option -> feature/category-option
    branch 'feature/category-option' set up to track 'origin/feature/category-option'.

    La demande de tirage est feature/category-option → main, et sa description est docs/pull-request.md.

Voici la description. Lisez-la comme un réviseur, avec les différences ouvertes :

docs/pull-request.md
# Pull request: report by category, and one line per team
Branch: `feature/category-option` → `main`
## What and why
- Grace asked for the report of one or a few categories
(`docs/tasks/category-option.md`).
- Grace's bug: with the web form's export, one team appeared under several
names (`docs/tasks/category-names-bug.md`).
## Requirement → change → evidence
| Requirement | Change (file) | Evidence |
|---|---|---|
| 1. Count only the chosen categories | `report.py` `build_summary(..., categories)` | `test_one_category` |
| 2. The option can be given more than once | `cli.py` `action="append"` | `test_a_ticket_in_any_chosen_category_counts`, `test_report_for_some_categories` |
| 3. Capital letters and spaces do not matter | `report.py` uses `clean_category` | `test_category_name_ignores_capital_letters_and_spaces` |
| 4. `categories` key only with the option | `report.py` | `test_categories_key_only_with_the_option`, `test_baseline.py` |
| 5. Whole-file counts unchanged | `report.py` filters after the totals | `test_categories_do_not_change_the_whole_file_counts` |
| 6. Unknown category is not an error | (no code needed) | `test_unknown_category_selects_nothing` |
| 7. Help and README describe the option | `cli.py` help, `README.md` | `test_help_describes_the_category_option`, `test_readme.py` |
| Bug: one line per team | `parsing.py` `clean_category` cleans first | `test_capital_letters_do_not_make_a_new_category` (fails before the fix), `test_web_form_export_has_one_line_per_team` |
## How I checked it
```sh
python -m pytest # 42 passed
ruff check .
ruff format --check .
python -m ticket_cleaner data/web-form-export.csv --category Sign-in
```
## Use of a coding assistant
An assistant suggested the first version of the option and of the fix. I read
every line, ran the tests myself, and changed or rejected some suggestions:
see `DECISIONS.md`. The regression test was written first and failed on the old
code.
## What a reviewer should look at
- `parsing.py`: the fix changes how every category is stored. Reports of older
files can change where a category had capital letters (`LOGIN` → `login`).
- `CATEGORY_ALIASES` is owned by the web form's team.

Deux parties sont nouvelles par rapport au cours sur Git. Utilisation d’un assistant de programmation indique clairement ce que l’assistant a fait et ce que vous avez fait. Elle ne cache pas l’assistant et ne le blâme pas. Points à examiner par le réviseur indique le changement du rapport pending présenté dans le problème ci-dessus. Vous l’avez trouvé; le réviseur n’a plus à le chercher.

Sur GitHub, les étapes sont les mêmes jusqu’à la poussée. Ensuite, Compare & pull request (comparer et ouvrir une demande de tirage) ouvre un formulaire. Collez la description, réglez base (branche cible) sur main, puis sélectionnez Create pull request (créer une demande de tirage). C’est facultatif et ce cours ne l’exige pas.

Kwame révise : un nouveau clone, un nouvel environnement

Section intitulée « Kwame révise : un nouveau clone, un nouvel environnement »

Kwame ne se fie pas à « 42 tests réussis » dans une description, même celle d’Amira. Il lance lui-même les vérifications, dans un nouveau clone, avec un nouvel environnement. C’est la vérification de fin de module. Vous la faites maintenant dans le rôle de Kwame.

  1. Clonez le dépôt distant dans un nouveau dossier, à côté du projet, puis passez à la branche :

    Fenêtre de terminal
    cd ~/projects
    git clone ticket-cleaner-remote.git kwame-review
    cd kwame-review
    git switch feature/category-option
    Sortie
    Cloning into 'kwame-review'...
    done.
    Switched to a new branch 'feature/category-option'
    branch 'feature/category-option' set up to track 'origin/feature/category-option'.
  2. Créez un nouvel environnement à partir du fichier de verrouillage. Désactivez d’abord l’ancien avec deactivate :

    Fenêtre de terminal
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install -r requirements-lock.txt
  3. Lancez chaque vérification de la description depuis ce clone :

    Fenêtre de terminal
    python -m pytest
    ruff check .
    ruff format --check .
    python -m ticket_cleaner data/web-form-export.csv --category Sign-in
    python -m ticket_cleaner data/web-form-export.csv
    Output (the author's run, the end of each check)
    ============================== 42 passed in 0.06s ==============================
    All checks passed!
    24 files already formatted

    Le premier rapport contient "by_category": {"login": 4} et "categories": ["login"]. Le second, sans l’option, contient {"account": 1, "billing": 3, "login": 4, "shipping": 2} : une ligne par équipe.

  4. Lisez le changement comme un réviseur : git diff main...feature/category-option. Kwame pose sa question habituelle : « Que peut toucher ce changement? » Répondez à partir des différences. Il touche deux clés du rapport et une règle de nettoyage appliquée à chaque billet. Il n’ajoute aucun accès aux fichiers ni aucun paquet, et il n’envoie rien à l’extérieur.

Les mêmes résultats dans un nouveau clone prouvent que chaque fichier nécessaire est enregistré dans un commit. Ils prouvent aussi que rien ne dépend de votre propre environnement.

Les points à faire réviser par une personne ou un spécialiste du domaine

Section intitulée « Les points à faire réviser par une personne ou un spécialiste du domaine »

Aucun test ne peut répondre à certaines questions, car la réponse se trouve hors du code. Nommez-les dans la demande de tirage et dans DECISIONS.md, avec la personne qui peut répondre :

Trois cases sur une rangée. ticket-cleaner-assist, le projet d'Amira, sur feature/category-option avec docs/pull-request.md, 42 tests réussis, aucune erreur ruff. Une flèche étiquetée git push -u vers ticket-cleaner-remote.git, un dépôt nu, le dépôt distant de l'équipe, avec main et feature/category-option. Une flèche étiquetée git clone vers kwame-review, le clone de Kwame, avec un nouveau .venv créé depuis requirements-lock.txt, 42 tests réussis, et Sign-in donne login 4. En dessous, trois cases orange : les points à faire réviser par une personne ou un spécialiste du domaine. Les anciens rapports changent : la correction change la façon d'enregistrer chaque catégorie; le rapport pending du fichier d'exemple passe de LOGIN 1 et billing 1 à billing 1 et login 1; qui lit les anciens chiffres? La liste d'alias : CATEGORY_ALIASES doit correspondre au formulaire Web; l'équipe de Grace est responsable du formulaire, donc elle seule peut dire si la liste est complète. Les exportations réelles : les tests utilisent des données inventées; une exportation réelle peut contenir d'autres graphies, par exemple Log in avec un espace.
Les vérifications accompagnent la branche, et un nouveau clone les répète. Les questions en orange ne suivent pas : une personne doit y répondre.
Description textuelle du diagramme

Amira pousse la branche vers ticket-cleaner-remote.git. Kwame la clone, crée un nouvel environnement depuis le fichier de verrouillage et obtient 42 passed et {"login": 4} pour Sign-in.

Trois questions demandent encore une personne :

  • Les anciens rapports changent. Le rapport pending du fichier d’exemple passe de {"LOGIN": 1, "billing": 1} à {"billing": 1, "login": 1}. Grace décide comment l’expliquer à son équipe.
  • La liste d’alias. CATEGORY_ALIASES doit correspondre au formulaire Web. L’équipe de Grace est responsable du formulaire.
  • Les exportations réelles. Les tests utilisent des données inventées. Une exportation réelle peut contenir d’autres graphies, comme Log in avec un espace.

Une révision par un spécialiste du domaine reconnaît honnêtement les limites des connaissances du code. Kwame approuve le code, et Grace répond aux trois questions. La branche peut ensuite être fusionnée, comme dans le cours sur Git.

Expliquez chaque ligne importante avant chaque demande de tirage, peu importe qui l’a écrite. Avec un assistant, personne d’autre n’a lu le code. Si vous ne pouvez pas expliquer une ligne, comprenez-la ou supprimez-la.

Modifiez volontairement des lignes pour les rendre incorrectes, surtout les plus importantes : une correction, une condition, une clé de sortie. Cela montre quelles lignes n’ont qu’un seul test pour les protéger.

Demandez une révision par une personne du domaine quand la réponse dépend de personnes ou de données hors du projet. Écrivez la question et le nom de la personne. Ne répondez pas au hasard.

Cela demande du temps avant la révision, mais en fait gagner davantage pendant celle-ci. Un tableau de traçabilité permet au réviseur de vérifier une modification en quelques minutes. « Corrections faites, tests réussis » oblige le réviseur à revenir vers vous avec des questions.

Erreur courante

git push : does not appear to be a git repository (ne semble pas être un dépôt Git)

Symptôme : vous poussez la branche pour la première fois, et Git refuse :

Sortie
fatal: '../ticket-cleaner-remote.git' does not appear to be a git repository
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.

Cause : le dépôt nu est au mauvais endroit. Ici, git init --bare a été exécuté dans le projet, car l’étape cd .. a été oubliée. Le chemin du dépôt distant, ../ticket-cleaner-remote.git, pointe vers un dossier qui n’existe pas.

Diagnostic : git status --short montre le dépôt nu comme un nouveau dossier dans le projet :

Sortie
?? ticket-cleaner-remote.git/

Correction : supprimez ce dossier dans le projet, après avoir vérifié son nom : rm -rf ticket-cleaner-remote.git (Windows : Remove-Item -Recurse -Force ticket-cleaner-remote.git). Refaites ensuite l’étape 6, en commençant par cd ... N’incluez jamais un dépôt nu dans un commit (enregistrement de modifications) du projet.

La vérification de fin de module : exécutez les vérifications vous-même et expliquez chaque modification importante. Montrez ces éléments :

  1. Dans kwame-review, un nouveau clone avec un nouvel environnement, les vérifications réussissent. Vous voyez 42 passed (42 tests réussis), All checks passed! (toutes les vérifications ont réussi) et 24 files already formatted (24 fichiers déjà formatés), ainsi que les deux rapports des étapes de Kwame.
  2. Pour cinq lignes importantes de git diff main...feature/category-option -- ticket_cleaner/, donnez les quatre réponses dans vos mots : quoi, pourquoi, quel test, quoi d’autre. Utilisez au moins une ligne de chacun des trois fichiers.
  3. La ligne que vous avez volontairement rendue incorrecte à l’étape 3, et le test qui a détecté le problème.
  4. Une question à poser à une personne du domaine, pas encore dans la demande de tirage, avec la personne qui peut répondre.
Afficher une solution détaillée

Cinq lignes, quatre réponses chacune :

Ligne Quoi Pourquoi Quel test Quoi d’autre
parsing.py 23 : text = clean_text(value) " LOGIN " → "login" avant la recherche d’alias le bogue de Grace : une ligne par équipe test_capital_letters_do_not_make_a_new_category (10 tests échouent sans cette ligne) chaque catégorie de chaque fichier, donc les anciens rapports changent (LOGIN → login)
cli.py 33 : action="append" --category billing --category shipping donne une liste contenant les deux catégories critère 2 test_report_for_some_categories (le seul) sans cette ligne, la dernière option l’emporte, sans avertissement
report.py 40 : chosen = sorted({clean_category(name) ...}) "Sign-in" → ["login"]; doublons supprimés, liste triée critères 3 et 4, et noms du formulaire Web test_web_form_names_work_in_the_category_option et 3 autres la clé categories montre les noms nettoyés, pas ce que l’utilisateur a saisi
report.py 41 : selected = [... if ticket.category in chosen] garde seulement les billets des catégories choisies critère 1 test_one_category cette ligne s’exécute après filter_by_status(), donc --status s’applique toujours
report.py 50–51 : if chosen is not None: ajoute categories seulement avec l’option critère 4, et feuille de calcul de Grace test_categories_key_only_with_the_option, tests/test_baseline.py le rapport sans l’option reste identique à celui d’avant

Une question pour une personne du domaine : « Autre chose lit-il reports/summary.json, par exemple un script de l’équipe des finances? Si oui, son responsable doit connaître la clé categories. » La personne : Grace, qui sait qui reçoit le rapport.

Vous avez terminé le module quand vous pouvez montrer ces éléments dans votre propre projet :

  • git log --oneline montre treize commits. Les trois derniers sont Describe the pull request (décrire la demande de tirage), Document the cleaning rule, the limitations and the decisions (documenter la règle de nettoyage, les limites et les décisions) et Clean the --category names with the same rule as the tickets (nettoyer les noms de –category avec la même règle que les billets). Après une réinitialisation, vous avez moins de commits, et c’est normal.

  • python -m pytest affiche 42 passed, dans votre projet et dans kwame-review.

  • git branch -vv montre les deux branches avec une branche de suivi sur origin.

  • Sur macOS et Linux, cette commande n’affiche rien, car votre projet correspond à l’instantané end-of-m05 :

    Fenêtre de terminal
    diff -rq . ../nextia-learning-labs/C15/snapshots/end-of-m05 -x .git -x .venv -x reports -x __pycache__ -x .pytest_cache -x .ruff_cache

Réinitialisation. Si votre projet ne fonctionne plus, suivez les étapes de réinitialisation de Contexte et limites. Utilisez l’instantané end-of-m04 au lieu de end-of-m01. Ces étapes gardent main au début du cours, pour que la demande de tirage montre toute la modification. La dernière ligne de python -m pytest est alors 39 passed (39 tests réussis). C’est le projet à la fin du module 4, prêt pour Réusiner de façon sélective. Pour passer à la fin de ce module, utilisez plutôt end-of-m05 : 42 passed. Si ticket-cleaner-remote.git ou kwame-review existent déjà, renommez-les aussi avant l’étape 6.

Vérifiez votre compréhension

Qu'est-ce qui rend une ligne d'une modification « importante »? Donnez une ligne importante et une ligne non importante du code modifié dans ce cours.

Afficher la réponse

Une ligne importante change le comportement, un contrat, les données stockées ou la sécurité. text = clean_text(value) dans parsing.py est importante : elle change la façon de stocker chaque catégorie. La chaîne de documentation de build_summary() ne l’est pas : elle ne change aucun comportement. Une chaîne de documentation incorrecte pourrait toutefois induire le prochain lecteur en erreur, alors vous la lisez quand même. Une vérification utile : si vous rendez volontairement la ligne incorrecte, un test devrait-il échouer? Pour une ligne importante, oui.

Vérifiez votre compréhension

Prédisez : vous remettez name.strip().lower() à la ligne 40 de report.py. Combien de tests échouent, et quelle conclusion en tirez-vous?

Afficher la réponse

Un seul : test_web_form_names_work_in_the_category_option, et 1 failed, 41 passed (1 test échoué, 41 réussis). Les autres tests utilisent des noms que les deux règles nettoient de la même façon. Cette ligne a donc exactement un test pour la protéger. Gardez ce test et nommez-le dans la demande de tirage et dans DECISIONS.md, comme le fait la décision 3. Si une modification future le supprime comme « doublon », le bogue des deux règles peut revenir malgré la réussite des autres tests.

Vérifiez votre compréhension

Les 42 tests ont réussi dans le dossier d'Amira. Pourquoi Kwame les relance-t-il dans un nouveau clone avec un nouvel environnement, et qu'est-ce qui pourrait différer?

Afficher la réponse

Une exécution réussie dans le dossier de l’auteur peut dépendre d’éléments absents des commits. Par exemple, un fichier jamais ajouté ou une modification jamais incluse dans un commit. Un autre exemple est un paquet présent dans l’environnement de l’auteur, mais absent du fichier de verrouillage. Un nouveau clone contient seulement ce qui a été poussé. Un nouvel environnement contient seulement ce que le fichier de verrouillage indique. Si les mêmes 42 tests y réussissent, la modification est complète et reproductible. C’est la même preuve que la nouvelle copie dans le cours Python pour l’ingénierie de l’IA en pratique.

Récapitulatif

Cette leçon

  • Comprendre le code par vous-même : vous expliquez chaque ligne importante sans l’assistant. Ce qu’elle fait, pourquoi, quel test échoue sans elle et ce qu’elle touche d’autre.
  • Un tableau de traçabilité relie chaque exigence à sa modification et à sa preuve. C’est l’élément central de docs/pull-request.md.
  • Rendez volontairement une ligne incorrecte pour voir quel test la protège. Deux lignes de cette modification ont exactement un test.
  • La correction change aussi le rapport pending du fichier d’exemple (LOGIN → login). Aucun test ne l’a détecté; la lecture, oui. C’est maintenant dans la demande de tirage.
  • Le nouveau clone et le nouvel environnement de Kwame : 42 passed. La liste d’alias, les vraies exportations et les anciens rapports ont encore besoin d’une vérification humaine.

Module 5 : Livrer un travail facile à maintenir

  • Réusinez seulement là où la modification l’exige : une règle de nettoyage a fait fonctionner --category Sign-in. Tout le reste est devenu une tâche distincte.
  • Documentez les décisions avec leurs preuves et n’écrivez aucune affirmation que vous n’avez pas vérifiée. tests/test_readme.py maintient deux affirmations du README exactes.
  • Ouvrez une demande de tirage qu’un réviseur peut vérifier seul : le tableau, les vérifications, l’utilisation d’un assistant et les questions ouvertes.
  • Votre projet correspond à end-of-m05, le projet de fin de cours : 42 passed.

Le cours

Vous avez commencé avec un projet, une demande de fonctionnalité et un rapport de bogue. Vous avez préparé un environnement sûr et rédigé une tâche que quelqu’un peut vérifier. Vous avez révisé les modifications générées ligne par ligne, débogué à partir de preuves et livré une modification que vous pouvez expliquer. Ensuite, les études de cas appliquent les mêmes habitudes à deux petits projets nouveaux pour vous, écrits pour le cours. L’un contient un bogue dans du code inconnu; l’autre nécessite une mise à jour de dépendance. Vous devez en terminer un pour obtenir le certificat, avec le travail final.

Leçon suivante : Corriger un bogue dans un code inconnu