06 - Documentation, commits et ecrit#

Voici mes notes brutes. Elles sont mal ecrites, dans le desordre, avec des
raccourcis et des fautes. C est normal, c est de la matiere premiere.

DESTINATAIRE : [QUI_VA_LIRE : mon equipe / mon manager / un dev qui ne
connait pas le projet / un profil non technique]
OBJECTIF DU TEXTE : [QU_EST_CE_QUE_LE_LECTEUR_DOIT_FAIRE_OU_COMPRENDRE]
FORMAT ATTENDU : [message de commit / description de PR / note technique /
paragraphe de README / mail]
LONGUEUR MAXIMALE : [NOMBRE] lignes
TON : factuel, direct, sans marketing

REGLES :
- n ajoute aucune information que je n ai pas donnee
- si une information te manque pour que le texte tienne debout, ne
  l invente pas : liste-la a la fin sous le titre "IL ME MANQUE"
- phrases courtes, une idee par phrase
- pas de "il est important de noter que", pas de "dans le cadre de"
- garde les termes techniques exacts que j ai utilises

MES NOTES :
[COLLE_TES_NOTES_TELLES_QUELLES]

bon donc le dag ingest_orders il plantait 1 fois sur 5 en prod
c etait le retry qui reinserait les lignes deja mises
du coup j ai mis une cle d idempotence sur order_id + run_id
et un delete avant insert sur le run_id
teste sur 3 jours ca passe
par contre faut que la table ait un index sur run_id sinon le delete est lent
j ai ajoute l index dans la migration 0042

fix(ingest): rendre la tache load_to_postgres rejouable

La tache load_to_postgres echouait environ une execution sur cinq en
production avec une erreur UniqueViolation sur orders_pkey.

Cause : quand Airflow relancait la tache apres un echec partiel, les lignes
deja inserees lors de la premiere tentative etaient reinserees.

Correctif :
- suppression des lignes du run courant avant insertion, filtree sur run_id
- ajout d un index sur run_id (migration 0042) pour que cette suppression
  reste rapide

Verification : trois jours de donnees rejoues sans erreur, avec un nombre de
lignes identique a l attendu.

IL ME MANQUE
- le nombre de lignes exact verifie sur les trois jours
- le temps d execution avant et apres l ajout de l index

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

feat(api)!: send an email to the customer when a product is shipped

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Ecris le message de commit pour le diff ci-dessous.

Convention : Conventional Commits (type(scope): description)
Types autorises dans mon equipe : [feat, fix, docs, refactor, perf, test, chore]
Langue : [FRANCAIS / ANGLAIS]

Contraintes :
- premiere ligne : 72 caracteres maximum, a l imperatif, pas de point final
- ligne vide, puis un corps qui explique le POURQUOI, pas le comment
- le corps ne repete pas le diff : il donne le contexte que le code ne montre pas
- si c est un changement cassant, ajoute le pied BREAKING CHANGE:
- pas de "divers", "fix", "update" seuls

Contexte que le diff ne montre pas :
[TICKET / DECISION / CONTRAINTE / CE_QUE_TU_AS_ESSAYE_AVANT]

DIFF :
[COLLE_LE_RESULTAT_DE_git_diff_--staged]

Redige la description de pull request pour le diff ci-dessous.

Ticket : [REFERENCE]
Objectif de la PR en une phrase : [OBJECTIF]
Ce qui est hors perimetre : [CE_QUE_TU_N_AS_PAS_TRAITE_VOLONTAIREMENT]

Structure imposee :

## Pourquoi
[le probleme, en 3 lignes maximum, comprehensible sans lire le code]

## Ce qui change
[liste a puces, une ligne par changement, fichier concerne entre parentheses]

## Comment verifier
[les commandes exactes qu un relecteur peut lancer, et ce qu il doit voir]

## Risques
[ce qui peut casser, et ce qui a ete fait pour l eviter]

## Hors perimetre
[ce qui n est volontairement pas traite ici]

Regles : pas d adjectif promotionnel, pas de repetition du diff, et si une
section n a rien a dire, ecris "Aucun" au lieu de meubler.

DIFF :
[COLLE_LE_RESULTAT_DE_git_diff_main...HEAD]

Format this data into a GitHub flavored markdown table that I can paste into
a GitHub pull request description.

[COLLE_ICI_TES_CHIFFRES_BRUTS]

Ajoute des docstrings aux fonctions de @[CHEMIN/FICHIER.py].

Style : [GOOGLE / NUMPY / REST] - suis exactement le style deja utilise
dans @[CHEMIN/FICHIER_EXEMPLAIRE.py]

Chaque docstring doit contenir :
- une premiere ligne a l imperatif ("Calcule...", "Retourne...", "Charge...")
- les arguments : nom, type, ce qu on attend comme valeur
- la valeur de retour : type et signification
- les exceptions levees et dans quel cas
- les effets de bord (ecriture disque, appel reseau, modification d etat)
- un exemple d appel avec des valeurs realistes de mon domaine

Contraintes :
- ne modifie AUCUNE ligne de code, uniquement les docstrings
- n ajoute pas de docstring aux fonctions privees triviales
- si tu ne comprends pas ce que fait une fonction, ecris
  "TODO: comportement a confirmer" plutot que d inventer

def parse_amount(raw: str | None) -> float | None:
    """Convertit un montant textuel en flottant.

    Accepte les separateurs francais et anglo-saxons ainsi que le symbole
    monetaire en prefixe. Retourne None pour toute valeur non interpretable,
    afin que le pipeline ne s arrete pas sur une ligne sale.

    Args:
        raw: Montant brut issu de l API, par exemple "1 234,56" ou "N/A".

    Returns:
        Le montant en flottant, ou None si la valeur est non interpretable.

    Raises:
        Aucune. Les erreurs de conversion sont converties en None.

    Example:
        >>> parse_amount("1 234,56")
        1234.56
    """

Ecris le README.md de ce repo, pour un developpeur ou data engineer qui
arrive sur le projet et doit etre autonome en 30 minutes.

Fichiers ou tu dois verifier les commandes avant de les ecrire :
@[LISTE_TES_FICHIERS_DE_CONFIG : pyproject.toml, Makefile, docker-compose.yml,
dbt_project.yml, .github/workflows/]

Structure imposee :
1. Une phrase : a quoi sert ce projet
2. Un schema texte du flux de donnees ou de l architecture
3. Prerequis : versions exactes (Python, base, outils)
4. Installation : les commandes, dans l ordre, copiables telles quelles
5. Lancement en local : la commande, et ce qu on doit voir si ca marche
6. Tests : la commande, et ce qu on doit voir
7. Variables d environnement : tableau nom / role / exemple de valeur
   (valeurs factices, jamais de vrai secret)
8. Structure des dossiers : tableau dossier / role
9. Les 3 pieges connus du projet

Regles :
- verifie chaque commande dans les fichiers de configuration du repo avant
  de l ecrire
- si une information est absente du repo, ecris "A COMPLETER" au lieu
  d inventer
- pas de section vide pour faire joli

Redige une note technique a partir de mes notes.

DESTINATAIRE : [EQUIPE_TECHNIQUE / MANAGER / MIXTE]
DECISION OU SUJET : [EN_UNE_PHRASE]
LONGUEUR : [NOMBRE] lignes maximum

Informations qui DOIVENT apparaitre (n en oublie aucune) :
- [INFO_1]
- [INFO_2]
- [INFO_3]

Structure imposee :
## Contexte        (3 lignes : la situation aujourd hui)
## Probleme        (3 lignes : ce qui ne va pas, avec un chiffre si possible)
## Options         (un tableau : option | cout | risque | delai)
## Recommandation  (laquelle, et pourquoi, en 5 lignes)
## Ce qu il faut decider  (les questions ouvertes, une par ligne)

Regles :
- si une information demandee n est pas dans mes notes, ecris
  "Non renseigne" a sa place
- pas de preambule, commence directement par "## Contexte"
- chiffre chaque affirmation quand mes notes le permettent

MES NOTES :
[COLLE_TES_NOTES]

Trop long. Refais en [NOMBRE] lignes maximum, en gardant uniquement ce
qu un lecteur presse doit savoir.

Trop vague. Remplace chaque affirmation generale par un chiffre, un nom de
fichier ou une commande. Si tu ne peux pas, supprime la phrase.

Ce n est pas mon vocabulaire. Reecris en utilisant exactement les termes
suivants a la place des tiens : [TERME_A] au lieu de [TERME_B], ...

Relis ton propre texte. Liste les affirmations que tu as ecrites et qui ne
sont PAS dans mes notes. Pour chacune, dis d ou elle vient.