docs: replace project structure with dev philosophy section
Replace the project directory tree and PR integration/versioning sections with a new "Philosophie de développement" section covering the NASA Power of Ten rules and security-by-design principles.
This commit is contained in:
+29
-82
@@ -9,16 +9,35 @@ On suit ces deux guides :
|
||||
|
||||
---
|
||||
|
||||
## Structure du projet
|
||||
## Philosophie de développement
|
||||
|
||||
```
|
||||
src/
|
||||
├── cli/ # Scripts CLI : zen-db
|
||||
├── core/ # Briques techniques : database, api, email, storage, cron, pdf, toast, payments
|
||||
├── features/ # Features utilisateur : auth, admin, provider
|
||||
├── modules/ # Modules métier : posts, invoice, nuage…
|
||||
└── shared/ # Composants, lib et styles partagés
|
||||
```
|
||||
### Power of Ten
|
||||
|
||||
Tout le code produit suit les principes du [NASA Power of Ten](https://en.wikipedia.org/wiki/The_Power_of_10:_Rules_for_Developing_Safety-Critical_Code) :
|
||||
|
||||
1. **Flux de contrôle simples** — pas de `goto`, pas de récursion non bornée, pas de pointeurs de fonctions imbriqués.
|
||||
2. **Boucles bornées** — toute boucle doit avoir une limite maximale d'itérations statiquement vérifiable.
|
||||
3. **Pas d'allocation dynamique après l'initialisation** — allouer les ressources en amont, libérer proprement.
|
||||
4. **Fonctions courtes et ciblées** — une fonction = une responsabilité, tient sur un écran.
|
||||
5. **Densité d'assertions élevée** — valider les préconditions, postconditions et invariants explicitement.
|
||||
6. **Portée des données minimale** — déclarer les variables au plus près de leur utilisation, limiter l'exposition.
|
||||
7. **Vérification systématique des retours** — chaque valeur de retour ou promesse rejetée doit être gérée.
|
||||
8. **Préprocesseur minimal** — éviter la magie implicite ; préférer la clarté à la concision.
|
||||
9. **Limiter les pointeurs** — une seule indirection par niveau ; pas d'aliasing caché.
|
||||
10. **Warnings = erreurs** — le linter et le compilateur doivent passer sans avertissement.
|
||||
|
||||
### Sécurité
|
||||
|
||||
Chaque contribution doit intégrer la sécurité dès la conception (*security by design*) :
|
||||
|
||||
- **Validation des entrées** — toute donnée externe (utilisateur, API tierce, fichier) est considérée malveillante jusqu'à preuve du contraire. Valider côté serveur, jamais uniquement côté client.
|
||||
- **Moindre privilège** — un module n'accède qu'aux ressources strictement nécessaires à sa fonction.
|
||||
- **Pas de secrets dans le code** — tokens, clés API, mots de passe passent exclusivement par des variables d'environnement ou un gestionnaire de secrets.
|
||||
- **Dépendances auditées** — lancer `npm audit` avant chaque publication ; ne pas introduire de dépendance avec des vulnérabilités connues non corrigées.
|
||||
- **Gestion des erreurs opaque** — les messages d'erreur exposés à l'utilisateur ne révèlent pas de détails internes (stack trace, chemin de fichier, requête SQL…).
|
||||
- **Protection contre les injections** — utiliser exclusivement des requêtes paramétrées ou des ORM éprouvés ; jamais de concaténation de chaînes SQL/shell.
|
||||
- **Authentification et sessions** — tokens signés, durée de vie limitée, révocation possible, rotation des secrets régulière.
|
||||
- **En-têtes HTTP de sécurité** — `Content-Security-Policy`, `X-Content-Type-Options`, `Strict-Transport-Security` configurés sur toutes les routes.
|
||||
|
||||
---
|
||||
|
||||
@@ -40,76 +59,4 @@ Remplacer `TOKEN` par le token généré.
|
||||
|
||||
```bash
|
||||
npm publish
|
||||
```
|
||||
|
||||
Le script `prepublishOnly` lance automatiquement le build avant la publication.
|
||||
|
||||
---
|
||||
|
||||
## Intégrer une Pull Request GitHub
|
||||
|
||||
Le dépôt GitHub est un miroir en lecture seule. On intègre manuellement les PRs de la communauté depuis Gitea.
|
||||
|
||||
### 1. Récupérer la branche du contributeur
|
||||
|
||||
```bash
|
||||
git fetch https://github.com/<contributeur>/core <branche>
|
||||
```
|
||||
|
||||
Par exemple :
|
||||
|
||||
```bash
|
||||
git fetch https://github.com/jdupont/core fix/auth-token-expiry
|
||||
```
|
||||
|
||||
### 2. Inspecter les changements
|
||||
|
||||
```bash
|
||||
git log FETCH_HEAD --oneline
|
||||
git diff main...FETCH_HEAD
|
||||
```
|
||||
|
||||
### 3a. Appliquer avec cherry-pick (recommandé pour un ou quelques commits)
|
||||
|
||||
```bash
|
||||
git cherry-pick <hash-du-commit>
|
||||
```
|
||||
|
||||
Pour plusieurs commits consécutifs :
|
||||
|
||||
```bash
|
||||
git cherry-pick <hash-début>^..<hash-fin>
|
||||
```
|
||||
|
||||
### 3b. Appliquer avec merge (pour une branche entière)
|
||||
|
||||
```bash
|
||||
git checkout -b integration/<description>
|
||||
git merge FETCH_HEAD
|
||||
# résoudre les conflits si nécessaire
|
||||
git checkout main
|
||||
git merge integration/<description>
|
||||
git branch -d integration/<description>
|
||||
```
|
||||
|
||||
### 4. Pousser vers Gitea
|
||||
|
||||
```bash
|
||||
git push origin main
|
||||
```
|
||||
|
||||
Le miroir GitHub se met à jour automatiquement. Fermer ensuite la PR sur GitHub en indiquant le hash du commit en commentaire.
|
||||
|
||||
---
|
||||
|
||||
## Bump de version
|
||||
|
||||
Modifier `"version"` dans `package.json` en suivant [semver](https://semver.org/) :
|
||||
|
||||
| Type | Version |
|
||||
|------|---------|
|
||||
| `fix` | PATCH `1.x.X` |
|
||||
| `feat` | MINOR `1.X.0` |
|
||||
| Breaking change | MAJOR `X.0.0` |
|
||||
|
||||
---
|
||||
```
|
||||
Reference in New Issue
Block a user