57 lines
2.7 KiB
Markdown
57 lines
2.7 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`
|
||
|
||
## 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>`
|
||
- Rapports: `tests/reports/agents/*.md`
|
||
- 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
|
||
|