133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
# Guide d’usage — 4NK_template (projet)
|
||
|
||
Ce document explique comment utiliser le template pour initier, documenter, contrôler et publier des projets dérivés, en respectant les standards qualité, sécurité et open source.
|
||
|
||
## 1. Pré‑requis
|
||
|
||
- Git opérationnel et accès à votre forge (Gitea recommandé)
|
||
- CI activée sur le repository
|
||
- bash disponible pour les agents (recommandé). À défaut, fallback PowerShell local
|
||
|
||
## 2. Démarrer un projet dérivé
|
||
|
||
1) Créer un repository à partir de 4NK_template
|
||
2) Copier/adapter la documentation depuis `docs/templates/**` vers votre `docs/**`
|
||
3) Tenir `docs/INDEX.md` et `CHANGELOG.md` à jour
|
||
4) Activer les workflows CI et vérifier `release-guard`/`security-audit`
|
||
|
||
## 2.1 Intégrer 4NK_template dans un projet existant
|
||
|
||
```bash
|
||
# Depuis le dépôt 4NK_template
|
||
bash scripts/deploy/setup.sh <git_url_du_projet> [--dest DIR] [--force]
|
||
# Compléter ensuite ~/.4nk_template/.env si nécessaire (OPENAI_*, BASE_URL, RELEASE_TOKEN)
|
||
```
|
||
|
||
### Intégration via Docker (recommandé)
|
||
|
||
```bash
|
||
# Build l’image unifiée
|
||
docker compose -f docker-compose.ci.yml build
|
||
|
||
# Appliquer le template depuis le conteneur (monter le repo projet sur /host)
|
||
docker run --rm -v "$PWD":/work -v "/chemin/vers/projet":/host 4nk-template-ci:latest \
|
||
bash -lc "/work/scripts/deploy/setup.sh file:///host/.git --dest /host"
|
||
```
|
||
|
||
## 3. Documentation
|
||
|
||
- Utiliser les squelettes de `docs/templates/**` comme base
|
||
- Documenter uniquement votre domaine applicatif (le template reste générique)
|
||
- À chaque changement de code/dépendance/CI, synchroniser la doc correspondante
|
||
|
||
## 4. Agents (contrôles)
|
||
|
||
- Recommandé (bash): `scripts/agents/run.sh [target_dir] [output_dir] [agent]`
|
||
- Windows fallback: `scripts/agents/run.ps1 -TargetDir . -OutputDir tests/reports/agents -Agent <nom>`
|
||
- Conteneur (option): `docker compose -f docker-compose.ci.yml up --abort-on-container-exit`
|
||
- Rapports: `tests/reports/agents/*.md`
|
||
- Variables utiles: `RUNNER_MODE`, `BASE_URL`, `REGISTRATION_TOKEN`
|
||
- Script helper: `scripts/dev/run_project_ci.sh`
|
||
- Auto‑corrections: `AUTO_FIX=1` pour créer la structure de tests et des squelettes docs
|
||
|
||
## 5. Remplacer la CI par une exécution locale (recommandé)
|
||
|
||
- CI neutre par défaut: `CI_SKIP=true` dans le workflow; réactivez en le passant à `false` côté dépôt.
|
||
- Commits: contrôles rapides avant commit
|
||
```bash
|
||
npx -y markdownlint-cli "**/*.md" --ignore "archive/**"
|
||
AUTO_FIX=1 SCOPE=changed scripts/agents/run.sh
|
||
# Ajoutez [skip ci] dans le message de commit pour éviter les runs distants
|
||
```
|
||
- Push: contrôles complets pré‑push
|
||
```bash
|
||
AUTO_FIX=1 SCOPE=all scripts/agents/run.sh
|
||
bash scripts/security/audit.sh || true
|
||
# Si outillage présent (exemples): cargo check / go vet / npx eslint / tsc --noEmit / ruff…
|
||
bash scripts/release/guard.sh || true
|
||
```
|
||
- Release locale (puis push tag)
|
||
```bash
|
||
echo "vYYYY.MM.P" > TEMPLATE_VERSION
|
||
git add TEMPLATE_VERSION CHANGELOG.md
|
||
git commit -m "[skip ci] chore(release): vYYYY.MM.P"
|
||
git tag -a vYYYY.MM.P -m "release: vYYYY.MM.P (latest)"
|
||
git push && git push origin vYYYY.MM.P
|
||
```
|
||
|
||
### Hooks conseillés
|
||
|
||
`.git/hooks/pre-commit`:
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
set -e
|
||
npx -y markdownlint-cli "**/*.md" --ignore "archive/**"
|
||
AUTO_FIX=1 SCOPE=changed scripts/agents/run.sh
|
||
```
|
||
|
||
`.git/hooks/pre-push`:
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
set -e
|
||
AUTO_FIX=1 SCOPE=all scripts/agents/run.sh
|
||
bash scripts/security/audit.sh || true
|
||
bash scripts/release/guard.sh || true
|
||
```
|
||
- Agents utiles en premier passage: `documentation`, `quality-technique`, `open-source`, `securite`, `deploiement`
|
||
|
||
## 5. Qualité et CI
|
||
|
||
- Jobs attendus: qualité, tests (catégories pertinentes), documentation, security‑audit, bash‑required, release‑guard
|
||
- `bash-required` garantit la présence de bash et du runner des agents
|
||
- `release-guard` bloque les publications si tests/doc/build/sécurité/version/changelog/tag ne sont pas cohérents
|
||
|
||
## 6. Sécurité
|
||
|
||
- Secrets uniquement via la CI (variables d’environnement), jamais en clair dans le dépôt
|
||
- Audit sécurité automatisé (job `security-audit`) et remédiations tracées dans `CHANGELOG.md`
|
||
|
||
## 7. Workflow quotidien
|
||
|
||
- Éditer: code et documentation (toujours en parallèle)
|
||
- Exécuter: tests locaux, agents (diagnostics)
|
||
- Vérifier: sorties CI, rapports `tests/reports/`
|
||
- Commiter: messages clairs, PR petites et ciblées
|
||
|
||
## 8. Publication
|
||
|
||
- Choisir `latest` (tag `vX.Y.Z`) ou `wip` (ex: `vX.Y.Z-wip.N`)
|
||
- Aligner: fichier de version, `CHANGELOG.md`, tag git
|
||
- Déployer si pipeline défini; sinon documenter la procédure
|
||
|
||
## 9. Dépannage
|
||
|
||
- Agents fallback PowerShell si bash indisponible localement
|
||
- Consulter `tests/reports/agents/*.md` pour les écarts à corriger
|
||
- Vérifier les logs de la CI et le job `release-guard`
|
||
|
||
## 10. Bonnes pratiques
|
||
|
||
- Pas d’exemples applicatifs dans le template
|
||
- Toujours mettre à jour la documentation et le changelog
|
||
- Réduire la dérive: synchroniser régulièrement vos projets avec les squelettes et standards
|