Conventions

Les règles d'écriture de l'API. Elles ne sont pas des goûts personnels : chacune évite un problème déjà rencontré.

Langues

Quoi	Langue	Pourquoi
Code, noms, commentaires de l'API	anglais	le code se lit avec l'écosystème Elixir, en anglais
Messages d'erreur de l'API	anglais, toujours avec un code	les clients traduisent le code, jamais la phrase
Textes des e-mails	anglais dans le code, traduits par Gettext	la phrase anglaise est la clé de traduction
Commits et descriptions de PR	anglais	l'historique du dépôt est en anglais
Cette documentation	français	l'équipe et la soutenance

Où mettre le code

• Une règle du métier va dans un contexte (lib/timemanager/), jamais dans un contrôleur.
• Un droit va dans Authorization, jamais dans un contrôleur.
• Les champs envoyés sont choisis par une vue JSON, jamais en renvoyant un schéma tel quel.
• Une écriture de plusieurs lignes (un pointage et sa journée, une modification et son journal) se fait dans une transaction : tout ou rien.
• Une règle qui doit tenir à coup sûr (unicité, une seule journée en cours) a aussi sa contrainte en base.

Écrire une fonction qui peut échouer

Elle renvoie {:ok, valeur} ou {:error, raison}, et le contrôleur l'enchaîne avec with. Une erreur nouvelle a toujours un code :

# une valeur refusée (422)
add_error(changeset, :start, "overlaps another working time", code: :overlaps)

# une action qui ne correspond pas à l'état (409)
Repo.rollback({:conflict, :already_clocked_in})

Puis on ajoute le code à la page Erreurs.

La mise en forme

mix format lib/timemanager/clocks.ex test/timemanager/clocks_test.exs

Formater les fichiers touchés, pas tout le projet

Certains fichiers du dépôt ont des fins de ligne Windows (CRLF). mix format sans argument les réécrit tous : la PR montre alors des centaines de lignes modifiées qui n'ont rien à voir avec elle, et elle devient illisible. L'alias mix precommit contient un mix format sans argument : si tu l'utilises, vérifie le git diff --stat avant de commiter.

Un fichier déjà mal formaté sur develop ne doit pas avoir plus de lignes à reformater après ta PR : formate tes lignes, pas tout le fichier.

Les migrations

• Additives autant que possible : ajouter plutôt que renommer ou supprimer.
• Jamais modifier une migration déjà fusionnée : en écrire une nouvelle.
• docs/database.mmd mis à jour dans la même PR, un commentaire par colonne.

Les secrets

Aucune clé, aucun mot de passe dans le code, un commit, un test ou un message. Les identifiants des seeds viennent de variables d'environnement (ADMIN_PASSWORD, DEMO_PASSWORD). En dev et en test, des secrets factices sont écrits dans config/dev.exs et config/test.exs : ils ne servent jamais en production.

Git

Quoi	Convention	Exemple
Branche	feat/, fix/ ou docs/, puis le sujet	feat/api-explicit-clocks
Commit	type(portée): ce que ça fait, à l'impératif	feat(api): explicit and replay-safe clocks and breaks
PR	vers develop, une notion par PR

La description d'une PR suit toujours le même plan :

Section	Contenu
Why	le problème, avec un exemple concret
What	ce qui change, fichier par fichier ou par thème
Not in this PR	ce qui est volontairement laissé pour plus tard
Checked	ce qui a été vérifié : tests, navigateur, Swagger

Avant d'ouvrir une PR

• [ ] mix test passe en entier
• [ ] seuls les fichiers touchés sont formatés
• [ ] la route est décrite dans Swagger (sinon api_docs_test.exs échoue)
• [ ] la documentation est à jour : schéma de la base, codes d'erreur, page concernée
• [ ] aucun fichier hors sujet dans la PR (git diff --stat develop)