Skip to content

Commit 5e0a8ec

Browse files
MopoloMopolo
committed
Mise en place d'ADR
1 parent 6abc678 commit 5e0a8ec

3 files changed

Lines changed: 237 additions & 0 deletions

File tree

‎doc/decisions/ADR-001-doctrine-orm.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
Id: ADR-001
3+
Date: 2026-03-01
4+
Statut: Proposé
5+
---
6+
7+
# Doctrine ORM
8+
9+
## Contexte
10+
11+
Le projet web de l'AFUP a beaucoup d'historique et a vu passer beaucoup d'évolutions du PHP.
12+
13+
Il y a à ce jour 3 façon d'accéder à la base de données :
14+
- [Ting][ting] : un datamapper léger
15+
- [Doctrine DBAL][doctrine-dbal] : un query builder
16+
- La classe `Base_De_Donnees` : un wrapper autour des fonctions `mysqli_*`
17+
18+
## Décision
19+
20+
Les accès à la base de données se font via l'utilisation de soit [Doctrine DBAL][doctrine-dbal], soit [Doctrine ORM][doctrine-orm].
21+
22+
### Détails d'implémentation (optionnel)
23+
24+
## Entité
25+
26+
Une entité doit déclarer ses propriétés fortement typées et en `public` (au lieu d'avoir des getters/setters).
27+
28+
```php
29+
use Doctrine\ORM\Mapping as ORM;
30+
31+
#[ORM\Entity]
32+
#[ORM\Table(name: 'exemple')]
33+
class Exemple
34+
{
35+
#[ORM\Id]
36+
#[ORM\GeneratedValue]
37+
#[ORM\Column]
38+
public ?int $id = null;
39+
40+
#[ORM\Column(length: 255, nullable: false)]
41+
public string $nonNullbale;
42+
43+
#[ORM\Column(length: 255, nullable: true)]
44+
public ?string $nullable = null;
45+
}
46+
```
47+
48+
## Repository
49+
50+
Un repository doit hériter de la classe de base `\AppBundle\Doctrine\EntityRepository` et doit implémenter le
51+
constructeur avec l'entité concernée.
52+
53+
```php
54+
use AppBundle\Exemple\Entity\Exemple;
55+
use AppBundle\Doctrine\EntityRepository;
56+
use Doctrine\Persistence\ManagerRegistry;
57+
58+
/**
59+
* @extends EntityRepository<Exemple>
60+
*/
61+
final class ExempleRepository extends EntityRepository
62+
{
63+
public function __construct(ManagerRegistry $registry)
64+
{
65+
parent::__construct($registry, Exemple::class);
66+
}
67+
}
68+
```
69+
70+
## Raisons
71+
72+
Cette décision rejoint plusieurs autres liées à la volontée du pôle de rendre le code plus accessible à la contribution
73+
et plus facile à la maintenance.
74+
75+
1. Doctrine est aujourd'hui le standard pour les accès à une base de données en PHP
76+
2. Il y a beaucoup d'opérations CRUD qui sont simplifiées avec Doctrine ORM
77+
3. Il reste possible d'affiner dans certains cas avec Doctrine DBAL
78+
79+
## Conséquences
80+
81+
### Positives
82+
83+
- Utiliser un ORM très populaire permet de faciliter la contribution
84+
- Les formulaires du back-office sont plus simples à rédiger (Symfony se pair bien avec Doctrine ORM)
85+
86+
### Négatives
87+
88+
- Cela implique une période de cohabitation et de refactor de l'ancien code
89+
90+
[ting]: https://packagist.org/packages/ccmbenchmark/ting
91+
[doctrine-dbal]: https://packagist.org/packages/doctrine/dbal
92+
[doctrine-orm]: https://packagist.org/packages/doctrine/orm

‎doc/decisions/ADR-002-langue-du-code.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
Id: ADR-002
3+
Date: 2026-03-01
4+
Statut: Proposé
5+
---
6+
7+
# Langue du code
8+
9+
## Contexte
10+
11+
Il y a deux problématiques avec la codebase à ce jour :
12+
13+
1. Le mélange des langues : certains mots "métier" sont en français, d'autres en anglais
14+
2. Certains mots "métier" anglais ne sont pas de l'anglais correct
15+
16+
## Décision
17+
18+
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
19+
temps en français.
20+
21+
| Contexte | Langue | Exemples | Justification |
22+
|----------------|----------|---------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
23+
| Domaine | Français | `Inscription`, `Facture`, `Adresse`, `StatutCommande` | Le code doit parler la langue du métier |
24+
| 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 |
25+
| Code technique | Anglais | `FileUploader`, `HttpClient`, `EventDispatcher` | Les mots du métier de dev sont toujours en anglais, pas de raison de les traduire |
26+
| Commentaires | Français | `// Vérification du numéro de facture` | Pour rester raccord avec le code métier |
27+
| 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 |
28+
29+
La logique principale est d'utiliser la langue déjà utilisée à l'oral pour chaque situation.
30+
31+
Par exemple, on ne dit pas "General Meeting" entre bénévoles, mais "Assemblée Générale".
32+
En revanche, on ne dit pas "Dépot" mais "Repository" par habitude dans notre métier.
33+
34+
## Raisons
35+
36+
{Listez les raisons principales qui justifient cette décision}
37+
38+
1. De par la nature francophone de l'AFUP, la majorité du vocabulaire de l'association est en français
39+
2. Le code métier anglais est difficile à naviguer, car il faut presque systématiquement le traduire pour le comprendre
40+
3. Certains mots sont difficiles voir impossible à traduire :
41+
- General Meeting ou General Assembly ? Les deux sont valides mais lequel choisir ?
42+
- Comment traduire `Antenne` ou `Super Apéro` et que ça reste compréhensible ?
43+
44+
## Alternatives considérées
45+
46+
1. **Tout en anglais** :
47+
- ne serait pas raccord avec le vocabulaire utilisé au jour le jour par les bénévoles
48+
- cette alternative nécessiterait la création d'un glossaire pour éxpliquer chaque mot anglais et sa traduction française
49+
- cela impliquerait de débattre le choix de la traduction de certains mots
50+
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
51+
52+
## Conséquences
53+
54+
### Positives
55+
56+
- La navigation et la compréhension du le code est plus simple
57+
- 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é
58+
- la contribution est facilité car il y a moins de vocabulaire à apprendre
59+
60+
### Négatives
61+
62+
- Les habitudes ont la vie dure, et écrire du code en français amènera toujours son lot de débat

‎doc/decisions/README.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Architecture Decision Records (ADR)
2+
3+
## Qu'est-ce qu'un ADR ?
4+
5+
Un ADR est un document décrivant une décision d'architecture pour le projet. Il doit contenir le contexte de la décision
6+
et ses effets sur le projet.
7+
8+
Ce n'est pas toujours nécessaire de créer un ADR, voici quelques exemples de situations où ça peut servir :
9+
10+
- Un refactor conséquent
11+
- L'ajout d'une librairie
12+
- Choisir une architecture particulière
13+
- Choisir un pattern ou une convention
14+
15+
## Comment créer un ADR ?
16+
17+
1. Créer un fichier nommé `ADR-XXX-le-super-titre.md` dans le dossier `doc/decisions`
18+
2. Remplir le fichier en utilisant [le template]
19+
3. Soumettre l'ADR à discussion (en ouvrant une PR et, si besoin, en venant en parler au point mensuel)
20+
4. Une fois que l'ADR est validé, mettre à jour son statut et le commit
21+
22+
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 à
23+
fait possible de faire une PR dédiée à un ADR.
24+
25+
## Template d'un ADR
26+
27+
```markdown
28+
---
29+
Id: ADR-XXX
30+
Date: Y-m-d
31+
Statut: {Proposé | Accepté | Déprécié | Remplacé par ADR-YYY}
32+
---
33+
34+
# {Titre court et descriptif}
35+
36+
## Contexte
37+
38+
{Décrivez le problème ou la situation qui nécessite une décision}
39+
40+
## Décision
41+
42+
{Décrivez la décision prise de manière claire et concise}
43+
44+
### Détails d'implémentation (optionnel)
45+
46+
{Si nécessaire, ajoutez des détails techniques sur l'implémentation}
47+
48+
## Raisons
49+
50+
{Listez les raisons principales qui justifient cette décision}
51+
52+
1. Raison 1
53+
2. Raison 2
54+
3. ...
55+
56+
## Alternatives considérées
57+
58+
{Listez les autres options envisagées et pourquoi elles n'ont pas été retenues}
59+
60+
1. **Alternative 1** : Pourquoi rejetée
61+
2. **Alternative 2** : Pourquoi rejetée
62+
63+
## Conséquences
64+
65+
### Positives
66+
67+
- Conséquence positive 1
68+
- Conséquence positive 2
69+
70+
### Négatives
71+
72+
- Conséquence négative 1
73+
- Conséquence négative 2
74+
75+
## Références
76+
77+
{Liens vers la documentation, articles, discussions qui ont influencé la décision}
78+
```
79+
80+
## Références
81+
82+
- [Architecture Decision Records](https://adr.github.io/)
83+
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)

0 commit comments

Comments
 (0)