4nk/4NK_template
Template
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4NK_template/docs/project/USAGE.md

3.0 KiB
Raw Blame History

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>
  • 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
  • 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