Mettre à jour les docs à partir des commits

Analyser l'historique git récent pour identifier les commits affectant le comportement visible par l'utilisateur et rédiger les mises à jour de documentation correspondantes.

Prérequis

• Vous devez être dans le repository git NemoClaw (NemoClaw).
• Le répertoire docs/ doit exister avec l'ensemble de documentation actuel.

Quand l'utiliser

• Après qu'un lot de fonctionnalités ou de correctifs ait été fusionné et que la documentation soit potentiellement obsolète.
• Avant une release, pour identifier les lacunes documentaires.
• Quand un contributeur demande « quels docs ont besoin d'être mis à jour ? »

Étape 0 : Charger la liste d'exclusion

Avant d'analyser les commits, lisez docs/.docs-skip s'il existe. Ce fichier liste les fonctionnalités et commits fusionnés mais qui ne doivent pas encore être documentés (expérimental, en révision, etc.).

cat docs/.docs-skip

Analysez ces sections du fichier :

• skip-features: — motifs de sous-chaîne à comparer avec les messages de commit et les chemins de fichiers modifiés. Tout commit dont le message ou la liste de fichiers contient une chaîne listée est exclu.
• skip-terms: — termes qui ne doivent jamais apparaître dans la documentation générée. Vérifiez tout contenu rédigé par rapport à cette liste avant d'écrire. Si une phrase rédigée contient un skip-term, supprimez cette phrase ou la section entière. C'est un blocage absolu — aucun skip-term ne peut apparaître dans aucune sortie de documentation.

Ignorez les lignes de commentaire (commençant par #) et les commentaires inline (tout après #).

Gardez la liste d'exclusion chargée en mémoire pour une utilisation tout au long de l'exécution du skill et de tout le processus de documentation.

Étape 1 : Identifier les commits pertinents

Déterminez la plage de commits. L'utilisateur peut en fournir une explicitement (par ex. « depuis v0.1.0 » ou « 30 derniers commits »). Si ce n'est pas le cas, par défaut les commits depuis la tête de la branche principale.

# Commits depuis un tag
git log v0.1.0..HEAD --oneline --no-merges

# Ou 50 derniers commits
git log -50 --oneline --no-merges

Filtrez pour identifier les commits susceptibles d'affecter la documentation. Appliquez chaque règle ci-dessous avant de continuer. Un commit exclu par une règle quelconque ne doit pas produire de changement documentaire.

1. Type de commit : Les commits feat, fix, refactor, perf changent souvent le comportement. Les commits docs sont déjà des changements documentaires. Les commits chore, ci, test requièrent rarement des mises à jour documentaires.
2. Fichiers modifiés : Les changements dans nemoclaw/src/, nemoclaw-blueprint/, bin/, scripts/ ou du code relatif aux politiques sont très significatifs.
3. Ignorer : Les changements limités à test/, .github/ ou aux modules internes uniquement.
4. Liste d'exclusion : Excluez tout commit dont le hash court apparaît dans skip-commits, ou dont le message de commit ou les chemins de fichiers modifiés contiennent une sous-chaîne skip-features. Signalez les commits ignorés dans le résumé final sous un titre « Skipped (docs-skip) ».
5. Matrice de support des agents : Ne documentez pas le support des agents (par ex. Claude Code, OpenHands, Goose) sauf si l'agent est listé dans la matrice de support des agents testés dans le quickstart ou la documentation de plateforme. Les commits qui ajoutent ou modifient le code d'intégration d'agents ne doivent produire des mises à jour documentaires que pour les agents déjà présents dans la matrice. Signalez les agents exclus sous « Skipped (not in agent matrix) » dans le résumé.

# Afficher les fichiers modifiés par commit pour évaluer l'impact
git log v0.1.0..HEAD --oneline --no-merges --name-only

Étape 2 : Cartographier les commits aux pages de documentation

Pour chaque commit pertinent, déterminez quelle(s) page(s) de documentation il affecte. Utilisez cette cartographie comme point de départ :

Si un commit ne correspond à aucune page existante mais introduit un concept visible par l'utilisateur, signalez-le comme nécessitant une nouvelle page.

Étape 3 : Lire les détails du commit

Pour chaque commit nécessitant une mise à jour documentaire, lisez la différence complète pour comprendre le changement :

git show <commit-hash> --stat
git show <commit-hash>

Extrayez :

• Ce qui a changé (nouveau flag, commande renommée, défaut modifié, nouvelle fonctionnalité).
• Pourquoi cela a changé (à partir du corps du message de commit, du problème lié ou de la description de PR).
• Tout changement cassant ou étapes de migration.

Étape 4 : Lire la page de documentation actuelle

Avant d'éditer, lisez la page de documentation cible complète pour comprendre son contenu et sa structure actuels.

Identifiez où le nouveau contenu devrait aller. Suivez la structure existante de la page.

Étape 5 : Rédiger la mise à jour

Avant d'écrire, vérifiez que le commit n'a pas été exclu à l'étape 1. Ne rédigez pas de contenu pour les commits appariés par la liste d'exclusion ou pour les intégrations d'agents ne figurant pas dans la matrice de support des agents testés. Après la rédaction, analysez le contenu pour tout skip-terms provenant de docs/.docs-skip. Supprimez toute phrase ou section contenant un skip-term. En cas de doute, ignorez le commit et signalez-le.

Rédigez la mise à jour documentaire en suivant ces conventions :

• Voix active, temps présent, deuxième personne.
• Pas de gras inutile. Réservez le gras aux étiquettes d'interface et aux noms de paramètres.
• Pas de tirets cadratin sauf s'ils sont utilisés avec parcimonie. Préférez les virgules ou les phrases séparées.
• Commencez les sections par une phrase d'introduction qui oriente le lecteur.
• Pas de superlatifs. Dites ce que fait la fonctionnalité, pas sa grandeur.
• Les exemples de code utilisent le langage console avec le préfixe d'invite $.
• Inclure l'en-tête SPDX si vous créez une nouvelle page.
• Correspondre au format frontmatter existant si vous créez une nouvelle page.
• Toujours écrire NVIDIA en majuscules. Faux : Nvidia, nvidia.
• Toujours capitaliser NemoClaw correctement. Faux : nemoclaw (en prose), Nemoclaw.
• Toujours capitaliser OpenShell correctement. Faux : openshell (en prose), Openshell, openShell.
• Ne pas numéroter les titres de section. Faux : « Section 1 : Configurer l'inférence » ou « Étape 3 : Vérifier ». Utilisez des titres descriptifs simples.
• Pas de deux-points dans les titres. Faux : « Inférence : Cloud et Local ». Écrivez plutôt « Inférence Cloud et Local ».
• Utiliser les deux-points uniquement pour introduire une liste. N'utilisez pas les deux-points comme ponctuation générale entre les clauses.

Lors de la mise à jour d'une page existante :

• Ajoutez du contenu au lieu logique dans la structure existante.
• Ne réorganisez pas les sections sauf si le changement l'exige.
• Mettez à jour toutes les références croisées ou les liens « Prochaines étapes » si pertinent.

Lors de la création d'une nouvelle page :

• Suivez le modèle frontmatter des pages existantes dans docs/.
• Ajoutez la page au toctree approprié dans docs/index.md.

Étape 6 : Présenter les résultats

Après avoir rédigé toutes les mises à jour, présentez un résumé à l'utilisateur :

## Mises à jour de docs à partir des commits

### Pages mises à jour
- `docs/reference/commands.md` : Ajout de la documentation de la commande `eject` (depuis le commit abc1234).
- `docs/reference/network-policies.md` : Mise à jour du schéma des politiques pour la nouvelle règle de sortie (depuis le commit def5678).

### Nouvelles pages nécessaires
- Aucune (ou listez les nouvelles pages créées).

### Ignorés (docs-skip)
- `feat(sandbox): add experimental-flag` (abc1234) — correspond à skip-features : « experimental-flag ».

### Commits sans impact documentaire
- `chore(deps): bump typescript` (abc1234) — dépendance interne, aucun changement visible par l'utilisateur.
- `test: add launch command test` (def5678) — changement de test uniquement.

Étape 7 : Construire et vérifier

Après avoir apporté des modifications, construisez la documentation localement :

make docs

Vérifiez :

• Les avertissements ou erreurs de construction.
• Les références croisées cassées.
• Le rendu correct du nouveau contenu.

Étape 8 : Étiqueter les PRs

Quand le workflow produit une pull request, appliquez l'étiquette documentation pour que les relecteurs puissent identifier les changements documentaires uniquement :

gh pr edit <number> --add-label documentation

Conseils

• En cas de doute sur la nécessité d'une mise à jour documentaire pour un commit, vérifiez si le message de commit référence un flag CLI, une option de configuration ou un comportement visible par l'utilisateur.
• Regroupez les commits connexes qui modifient la même page de documentation en une seule mise à jour plutôt que de faire plusieurs petites modifications.
• Si un commit est un changement cassant, ajoutez une note au début de la section pertinente en utilisant une admonition :::{warning}.
• Les PRs qui sont des refactorisations purement internes sans changement de comportement ne nécessitent pas de mises à jour documentaires, même si elles modifient des répertoires hautement significatifs.
• Pour supprimer la documentation d'une fonctionnalité fusionnée qui n'est pas prête pour la documentation publique, ajoutez-la à docs/.docs-skip. Supprimez l'entrée une fois que la fonctionnalité est prête à être documentée.

Exemple d'utilisation

L'utilisateur dit : « Mettez à jour la documentation pour tout ce qui a été fusionné depuis v0.1.0. »

1. Exécutez git log v0.1.0..HEAD --oneline --no-merges --name-only.
2. Filtrez pour les commits feat, fix, refactor, perf modifiant le code visible par l'utilisateur.
3. Cartographiez chacun sur une page de documentation.
4. Lisez les différences de commit et les pages de documentation actuelles.
5. Rédigez les mises à jour en suivant le guide de style.
6. Présentez le résumé.
7. Construisez avec make docs pour vérifier.