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
This commit is contained in:
+56
-17
@@ -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` |
|
||||
|
||||
---
|
||||
### 3. Build et publish
|
||||
|
||||
```bash
|
||||
npm publish
|
||||
```
|
||||
|
||||
@@ -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/) :
|
||||
|
||||
```
|
||||
<type>(<scope>): <description courte>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
```
|
||||
@@ -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 :
|
||||
|
||||
```
|
||||
<type>(<scope>): <description courte>
|
||||
```
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user