diff --git a/doc/decisions/ADR-001-langue-du-code.md b/doc/decisions/ADR-001-langue-du-code.md new file mode 100644 index 000000000..1f7aba14e --- /dev/null +++ b/doc/decisions/ADR-001-langue-du-code.md @@ -0,0 +1,68 @@ +--- +Id: ADR-001 +Date: 2026-03-01 +Statut: Proposé +--- + +# Langue du code + +## Contexte + +Il y a deux problématiques avec la codebase à ce jour : + +1. Le mélange des langues : certains mots "métier" sont en français, d'autres en anglais +2. Certains mots "métier" anglais ne sont pas de l'anglais correct + +## Décision + +Les mots "métier" doivent être rédigés dans la langue dudit métier, autrement dit, dans le cas de l'AFUP, la plupart du +temps en français. + +| Contexte | Langue | Exemples | Justification | +|----------------|----------|---------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| Domaine | Français | `Inscription`, `Facture`, `Adresse`, `StatutCommande` | Le code doit parler la langue du métier | +| Infrastructure | Hybride | `AntenneRepository`, `CommandeAdapter`, `FactureSender` | Les mots métier sont en français puisque le métier de l'asso est en français, et les mots techniques sont en anglais, pas de raison de les traduire | +| Code technique | Anglais | `FileUploader`, `HttpClient`, `EventDispatcher` | Les mots du métier de dev sont toujours en anglais, pas de raison de les traduire | +| Commentaires | Français | `// Vérification du numéro de facture` | Pour rester raccord avec le code métier | +| Tests Behat | Hybride | `When I press "Sauvegarder"` | Les phrases Behat proviennent d'une librairie et sont déjà en anglais, l'interface est en français | + +La logique principale est d'utiliser la langue déjà utilisée à l'oral pour chaque situation. + +Par exemple, on ne dit pas "General Meeting" entre bénévoles, mais "Assemblée Générale". +En revanche, on ne dit pas "Dépot" mais "Repository" par habitude dans notre métier. + +> [!NOTE] +> Les mots français dans le code doivent être écrits sans accents. +> +> Certains outils (Psalm, PHPStan, Doctrine, Git, SQL) ont du mal à les gérer +> donc on se simplifie les choses en ne mettant pas d'accents. +> +> Cela ne s'applique pas aux commentaires qui n'ont pas ce problème. + +## Raisons + +1. De par la nature francophone de l'AFUP, la majorité du vocabulaire de l'association est en français +2. Le code métier anglais est difficile à naviguer, car il faut presque systématiquement le traduire pour le comprendre +3. Certains mots sont difficiles voir impossible à traduire : + - General Meeting ou General Assembly ? Les deux sont valides mais lequel choisir ? + - Comment traduire `Antenne` ou `Super Apéro` et que ça reste compréhensible ? + +## Alternatives considérées + +1. **Tout en anglais** : + - ne serait pas raccord avec le vocabulaire utilisé au jour le jour par les bénévoles + - cette alternative nécessiterait la création d'un glossaire pour éxpliquer chaque mot anglais et sa traduction française + - cela impliquerait de débattre le choix de la traduction de certains mots +2. **Tout en français** : les mots techniques ont plus de sens à rester en anglais, car c'est la norme dans le métier de dev + +## Conséquences + +### Positives + +- La navigation et la compréhension du le code est plus simple +- Quand un ou une bénévole parle du site ou d'un sujet de l'association, il est plus simple de retrouver le code concerné +- la contribution est facilité car il y a moins de vocabulaire à apprendre + +### Négatives + +- Les habitudes ont la vie dure, et écrire du code en français amènera toujours son lot de débat diff --git a/doc/decisions/ADR-002-acces-base-de-donnees.md b/doc/decisions/ADR-002-acces-base-de-donnees.md new file mode 100644 index 000000000..6314bcf2a --- /dev/null +++ b/doc/decisions/ADR-002-acces-base-de-donnees.md @@ -0,0 +1,92 @@ +--- +Id: ADR-002 +Date: 2026-03-01 +Statut: Proposé +--- + +# Accès à la base de données + +## Contexte + +Le projet web de l'AFUP a beaucoup d'historique et a vu passer beaucoup d'évolutions du PHP. + +Il y a à ce jour 3 façon d'accéder à la base de données : +- [Ting][ting] : un datamapper léger +- [Doctrine DBAL][doctrine-dbal] : un query builder +- La classe `Base_De_Donnees` : un wrapper autour des fonctions `mysqli_*` + +## Décision + +Les accès à la base de données se font via l'utilisation de soit [Doctrine DBAL][doctrine-dbal], soit [Doctrine ORM][doctrine-orm]. + +### Détails d'implémentation + +## Entité + +Une entité doit déclarer ses propriétés fortement typées et en `public` (au lieu d'avoir des getters/setters). + +```php +use Doctrine\ORM\Mapping as ORM; + +#[ORM\Entity] +#[ORM\Table(name: 'exemple')] +class Exemple +{ + #[ORM\Id] + #[ORM\GeneratedValue] + #[ORM\Column] + public ?int $id = null; + + #[ORM\Column(length: 255, nullable: false)] + public string $nonNullbale; + + #[ORM\Column(length: 255, nullable: true)] + public ?string $nullable = null; +} +``` + +## Repository + +Un repository doit hériter de la classe de base `\AppBundle\Doctrine\EntityRepository` et doit implémenter le +constructeur avec l'entité concernée. + +```php +use AppBundle\Exemple\Entity\Exemple; +use AppBundle\Doctrine\EntityRepository; +use Doctrine\Persistence\ManagerRegistry; + +/** + * @extends EntityRepository + */ +final class ExempleRepository extends EntityRepository +{ + public function __construct(ManagerRegistry $registry) + { + parent::__construct($registry, Exemple::class); + } +} +``` + +## Raisons + +Cette décision rejoint plusieurs autres liées à la volontée du pôle de rendre le code plus accessible à la contribution +et plus facile à la maintenance. + +1. Doctrine est aujourd'hui le standard pour les accès à une base de données en PHP +2. Il y a beaucoup d'opérations CRUD qui sont simplifiées avec Doctrine ORM +3. Il reste possible d'affiner dans certains cas avec Doctrine DBAL + +## Conséquences + +### Positives + +- Utiliser un ORM très populaire permet de faciliter la contribution +- Les formulaires du back-office sont plus simples à rédiger (Symfony se pair bien avec Doctrine ORM) + +### Négatives + +- Cela implique une période de cohabitation et de refactor de l'ancien code + +[ting]: https://packagist.org/packages/ccmbenchmark/ting +[doctrine-dbal]: https://packagist.org/packages/doctrine/dbal +[doctrine-orm]: https://packagist.org/packages/doctrine/orm diff --git a/doc/decisions/README.md b/doc/decisions/README.md new file mode 100644 index 000000000..da855c408 --- /dev/null +++ b/doc/decisions/README.md @@ -0,0 +1,83 @@ +# Architecture Decision Records (ADR) + +## Qu'est-ce qu'un ADR ? + +Un ADR est un document décrivant une décision d'architecture pour le projet. Il doit contenir le contexte de la décision +et ses effets sur le projet. + +Ce n'est pas toujours nécessaire de créer un ADR, voici quelques exemples de situations où ça peut servir : + +- Un refactor conséquent +- L'ajout d'une librairie +- Choisir une architecture particulière +- Choisir un pattern ou une convention + +## Comment créer un ADR ? + +1. Créer un fichier nommé `ADR-XXX-le-super-titre.md` dans le dossier `doc/decisions` +2. Remplir le fichier en utilisant [le template] +3. Soumettre l'ADR à discussion (en ouvrant une PR et, si besoin, en venant en parler au point mensuel) +4. Une fois que l'ADR est validé, mettre à jour son statut et le commit + +Il est recommandé de soumettre un ADR dans la même PR que le code concerné. Si ce n'est pas pertinent, il reste tout à +fait possible de faire une PR dédiée à un ADR. + +## Template d'un ADR + +```markdown +--- +Id: ADR-XXX +Date: Y-m-d +Statut: {Proposé | Accepté | Déprécié | Remplacé par ADR-YYY} +--- + +# {Titre court et descriptif} + +## Contexte + +{Décrivez le problème ou la situation qui nécessite une décision} + +## Décision + +{Décrivez la décision prise de manière claire et concise} + +### Détails d'implémentation (optionnel) + +{Si nécessaire, ajoutez des détails techniques sur l'implémentation} + +## Raisons + +{Listez les raisons principales qui justifient cette décision} + +1. Raison 1 +2. Raison 2 +3. ... + +## Alternatives considérées + +{Listez les autres options envisagées et pourquoi elles n'ont pas été retenues} + +1. **Alternative 1** : Pourquoi rejetée +2. **Alternative 2** : Pourquoi rejetée + +## Conséquences + +### Positives + +- Conséquence positive 1 +- Conséquence positive 2 + +### Négatives + +- Conséquence négative 1 +- Conséquence négative 2 + +## Références + +{Liens vers la documentation, articles, discussions qui ont influencé la décision} +``` + +## Références + +- [Architecture Decision Records](https://adr.github.io/) +- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)