docs: reorganize and update developer documentation

- update README.md to simplify @zen/core description
- rewrite DEV.md standards section with clearer principles and remove publication section
- extract publication process to new PUBLICATION.md document
- rewrite REDACTION.md with simplified structure and two-context approach
- bump package version in package.json
This commit is contained in:
2026-04-25 08:30:23 -04:00
parent a9b4f127ea
commit 74ce6192f1
5 changed files with 138 additions and 173 deletions
+10 -44
View File
@@ -8,13 +8,15 @@ Pour les conventions de commit : [COMMITS.md](./dev/COMMITS.md).
Pour la procédure de publication du package : voir section [Publication](#publication) ci-dessous.
> **Contexte projet** : `@zen/start` est un CLI qui génère un projet Next.js avec le CMS `@zen/core` déjà intégré. Lors d'une assistance ou d'une revue, partez du principe que le rôle de ce package est de scaffolder — pas d'exécuter du code applicatif.
> **Contexte projet** : `@zen/start` est un CLI qui génère un projet Next.js avec `@zen/core` déjà intégré. Partez du principe que le rôle de ce package est de scaffolder, il génère une structure de projet, il n'exécute pas de logique applicative.
---
## Standards de code
### Principes généraux
**Les promesses ne s'ignorent pas.** Chaque `Promise` est `await`ée ou `.catch()`ée. Une promesse silencieuse qui échoue est un bug invisible.
**Les variables d'environnement et la documentation se mettent à jour avec le code.** Toute variable ajoutée, renommée ou supprimée doit être reflétée dans `.env.example`. Toute décision architecturale ou convention nouvelle doit être documentée dans le fichier `docs/` concerné.
**Une fonction, une responsabilité.** Si elle fait deux choses, c'est deux fonctions. Si elle ne tient pas sur un écran, la découper.
@@ -22,17 +24,17 @@ Pour la procédure de publication du package : voir section [Publication](#publi
**Les données entrantes sont suspectes.** On valide en entrée de fonction. On ne suppose pas que l'appelant a fait le travail.
**Les promesses ne s'ignorent pas.** Chaque `Promise` est `await`ée ou `.catch()`ée. Une promesse silencieuse qui échoue est un bug invisible.
**La portée des variables est minimale.** On déclare au plus près de l'usage. Pas de variables réutilisées pour deux rôles différents.
**ESLint passe sans avertissement.** Un warning ignoré aujourd'hui est un bug non détecté demain.
**Les commentaires reflètent toujours le comportement réel du code.** Un commentaire obsolète est pire qu'un commentaire absent — il induit en erreur. Quand on modifie une fonction, on met à jour son commentaire. Un commentaire qui contredit le code est un bug de documentation.
---
## Sécurité
### Données entrantes
Toute donnée externe est considérée malveillante par défaut : arguments CLI, chemins de fichiers, noms de projet fournis par l'utilisateur. On valide et on assainit avant tout usage dans des chemins ou des commandes shell.
**Données entrantes** : toute donnée externe est considérée malveillante par défaut. On valide côté serveur uniquement.
### Système de fichiers
@@ -44,40 +46,4 @@ const dest = path.join(targetDir, 'package.json')
// ✗
const dest = targetDir + '/package.json'
```
### Secrets
Aucun token, clé API ou credential dans le code. Le token d'authentification au registre npm est configuré localement, jamais commité.
---
## Publication
Le package `@zen/start` est publié sur le registre npm hébergé sur `https://git.hyko.cx`.
### 1. Configurer l'authentification
Créer un token d'accès dans Gitea (Settings → Applications → Generate Token), puis l'enregistrer localement :
```bash
npm config set //git.hyko.cx/api/packages/zen/npm/:_authToken TOKEN
```
Remplacer `TOKEN` par le token généré.
### 2. 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` |
### 3. Build et publish
```bash
npm publish
```
```