From ca0fafe6ff0eb3eb98516ffe8db716fb27d63fb6 Mon Sep 17 00:00:00 2001 From: Hyko Date: Mon, 13 Apr 2026 15:19:41 -0400 Subject: [PATCH] docs: rewrite DEV.md with security guidelines and structure Expand the development guide from a minimal overview into a comprehensive reference covering: - Code standards: single responsibility, control flow, input validation, promise handling, and variable scoping - Security section: treat all external input as malicious, use path.join over string concatenation, no secrets in code - Reorganize publication steps to include version bump before build/publish for a logical workflow - Add project context note clarifying the scaffolding role of @zen/start --- docs/DEV.md | 73 ++++++++++++++++++++++++-------- docs/dev/COMMITS.md | 56 ++++++++++++++++++++++++ docs/dev/{GUIDE.md => LANGUE.md} | 18 +------- 3 files changed, 113 insertions(+), 34 deletions(-) create mode 100644 docs/dev/COMMITS.md rename docs/dev/{GUIDE.md => LANGUE.md} (56%) diff --git a/docs/DEV.md b/docs/DEV.md index fe4013f..c1ba9d5 100644 --- a/docs/DEV.md +++ b/docs/DEV.md @@ -1,17 +1,60 @@ -# DEV +# Guide de développement -## Standards +Ce document couvre les conventions de code, les règles de sécurité et la procédure de publication du package `@zen/start`. -On suit ces deux guides : +Pour les conventions de rédaction : [LANGUE.md](./dev/LANGUE.md) et [REDACTION.md](./dev/REDACTION.md). -- [GUIDE.md](./dev/GUIDE.md) : conventions générales de rédaction et de structure -- [REDACTION.md](./dev/REDACTION.md) : règles de style, ton et formatage +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. --- -## Publier le package +## Standards de code -Le package `@zen/start` est publié sur le registre npm à `https://git.hyko.cx`. +### Principes généraux + +**Une fonction, une responsabilité.** Si elle fait deux choses, c'est deux fonctions. Si elle ne tient pas sur un écran, la découper. + +**Le flux de contrôle se lit de haut en bas.** Pas de récursion non bornée, pas de callbacks imbriqués à plus de deux niveaux. Quelqu'un qui lit le code pour la première fois doit pouvoir suivre l'exécution sans se perdre. + +**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. + +--- + +## 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. + +### Système de fichiers + +On ne construit jamais un chemin par concaténation de chaînes brutes. On utilise `path.join` ou `path.resolve` : + +```js +// ✓ +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 @@ -23,15 +66,7 @@ npm config set //git.hyko.cx/api/packages/zen/npm/:_authToken TOKEN Remplacer `TOKEN` par le token généré. -### 2. Build et publish - -```bash -npm publish -``` - ---- - -## Bump de version +### 2. Bump de version Modifier `"version"` dans `package.json` en suivant [semver](https://semver.org/) : @@ -41,4 +76,8 @@ Modifier `"version"` dans `package.json` en suivant [semver](https://semver.org/ | `feat` | MINOR `1.X.0` | | Breaking change | MAJOR `X.0.0` | ---- \ No newline at end of file +### 3. Build et publish + +```bash +npm publish +``` diff --git a/docs/dev/COMMITS.md b/docs/dev/COMMITS.md new file mode 100644 index 0000000..092925b --- /dev/null +++ b/docs/dev/COMMITS.md @@ -0,0 +1,56 @@ +# Conventions de commit + +Tous les messages de commit sont rédigés en **anglais**, en suivant le format [Conventional Commits](https://www.conventionalcommits.org/) : + +``` +(): +``` + +--- + +## Types + +| Type | Usage | +|------|-------| +| `feat` | New feature | +| `fix` | Bug fix | +| `refactor` | Code restructuring without behavior change | +| `style` | Formatting only (spaces, commas, no logic change) | +| `docs` | Documentation only | +| `test` | Add or update tests | +| `chore` | Maintenance, dependencies, build config | +| `perf` | Performance improvement | +| `revert` | Revert a previous commit | + +--- + +## Exemples + +``` +feat(auth): add OAuth2 login support +fix(api): handle null response from payment gateway +refactor(storage): extract upload logic into helper +docs(guide): add git commit message conventions +chore(deps): update dependencies +perf(db): cache user metadata on repeated reads +revert: revert "feat(auth): add OAuth2 login support" +``` + +--- + +## Règles + +- **Scope** : facultatif, précise la zone touchée `auth`, `api`, `storage`, `ui`, `config` +- **Description** : minuscules, sans point final, en anglais +- Un commit = une intention. Ne pas mélanger fix et refactor +- Pas de `wip`, `fix fix`, `oups` ou messages vides + +## Breaking changes + +Ajouter `!` après le type et un pied de page `BREAKING CHANGE:` : + +``` +feat(api)!: remove legacy query parameter + +BREAKING CHANGE: the `legacy` param is no longer accepted, use `version` instead. +``` diff --git a/docs/dev/GUIDE.md b/docs/dev/LANGUE.md similarity index 56% rename from docs/dev/GUIDE.md rename to docs/dev/LANGUE.md index f9f20a0..f5fc579 100644 --- a/docs/dev/GUIDE.md +++ b/docs/dev/LANGUE.md @@ -1,4 +1,4 @@ -# GUIDE +# LANGUE ## Langue du code @@ -16,22 +16,6 @@ Tout ce qui est **visible par l'utilisateur** est en **français** : - Slugs et noms de dossiers qui correspondent à des routes URL - Documentations, README.md -## Messages de commit Git - -Tous les messages de commit doivent être rédigés en **anglais**, en suivant le format conventional commits : - -``` -(): -``` - -Types courants : `feat`, `fix`, `refactor`, `style`, `docs`, `test`, `chore` - -Exemples : -- `feat(auth): add OAuth2 login support` -- `fix(api): handle null response from payment gateway` -- `docs(guide): add git commit message conventions` -- `chore(deps): update dependencies` - ## Guide de rédaction Se référer à `REDACTION.md` avant de rédiger tout contenu textuel.