shagghiesuperstar/hermes-skills

Regroupement de PR de documentation uniquement

Aperçu

De nombreuses petites pull requests de documentation sont plus faciles à examiner lorsqu'elles sont regroupées. Cette procédure copie les fichiers de plusieurs PR de documentation uniquement et révisées dans une nouvelle PR en brouillon, un commit par source. Les contenus des fichiers sont copiés exactement, sans modifications. Les PR sources ne sont pas modifiées. Un réviseur fusionne ensuite la PR de lot unique, et les PR sources se ferment via leur propre état, sans aucune action dans cette procédure.

Quand l'utiliser

• Plusieurs PR de documentation ouvertes ont été révisées, et chacune ne touche que des chemins de documentation.
• Un réviseur demande une seule PR qui les regroupe.

Ne pas utiliser cela pour du code, de la configuration ou toute PR source qui n'a pas été révisée.

Fonctionnalités

• Un worktree temporaire, de sorte que la copie de travail en cours n'est pas touchée.
• Un instantané en direct de l'état de chaque PR source, de sa base, de sa tête et de sa liste de fichiers, vérifié par rapport au commit de tête récupéré.
• Règles d'exclusion pour les PR qui sont fermées, qui touchent des chemins en dehors du dossier de documentation, qui entrent en collision avec la branche principale ou avec une autre PR ouverte.
• Un commit par source livrée, avec des assertions qui arrêtent l'exécution en cas de source défectueuse.
• Des vérifications sur les chemins modifiés avant le push, et un bloc de vérification qui compare chaque blob de fichier avec sa tête source.

Avantages

• Une source défectueuse arrête l'exécution au lieu de livrer partiellement.
• Le contenu de chaque fichier livré est prouvé identique à sa source.
• Les PR exclues sont listées avec la raison, donc rien n'est supprimé silencieusement.
• La PR de lot est ouverte en tant que brouillon, donc le réviseur prend la décision finale.

Procédure

1. Travailler dans un worktree temporaire. Récupérer la branche principale et les têtes des PR sources, puis créer une nouvelle branche à partir de la principale dans un dossier temporaire :

   git fetch origin main '+refs/pull/*/head:refs/remotes/origin/pr/*'
   git worktree add -b <batch-branch> <scratch-dir>/wt origin/main
   

   Si un fetch ou push HTTPS échoue sur l'authentification, exécutez cette commande avec le helper d'identifiants défini sur le CLI de l'hôte de code, par exemple -c credential.helper= -c 'credential.helper=!gh auth git-credential'. Ne modifiez pas la configuration stockée et n'imprimez pas de jeton.

2. Capturer l'état en direct une fois. Pour chaque PR source, lire son état, son indicateur de brouillon, sa branche de base, son commit de tête et sa liste de fichiers. Lister également les PR ouvertes pour les vérifications de collision. Affirmer que le commit de tête de chaque PR source est égal au commit refs/remotes/origin/pr/<n> récupéré.

3. Décider d'exclure ou de livrer, dans l'ordre des numéros. Exclure une PR, et enregistrer la raison, si l'une de ces conditions est vraie :

   • Elle n'est pas ouverte.
   • L'un de ses chemins est en dehors du dossier de documentation.
   • L'un de ses chemins existe déjà sur la branche principale. Pour un chemin déjà sur la principale, comparer les blobs. Un contenu identique signifie qu'il a été livré plus tôt. Un contenu différent signifie qu'il a besoin d'un rebasage.
   • Une autre PR ouverte modifie l'un de ses chemins.

4. Livrer chaque PR sous forme d'un commit. Pour chaque PR livrée, extraire ses fichiers de son commit de tête, et les commiter avec un message qui nomme la PR. Exécuter ceci dans une boucle qui affirme que la PR est ouverte, que la tête correspond, que les chemins sont dans le dossier de documentation, et qu'aucun d'eux n'est sur la principale. Une assertion échouée arrête l'exécution.

   git checkout <head-commit> -- <paths>
   git commit -m "docs: land #<n>"
   

5. Vérifier les modifications avant le push. Le nombre de fichiers modifiés en dehors du dossier de documentation doit être égal à zéro. Le nombre total de fichiers modifiés doit être égal à la somme des comptes de chemins par PR.

6. Construire le bloc de vérification. Pour chaque PR et chacun de ses chemins, comparer le blob au HEAD de la branche de lot avec le blob à la tête source. Afficher une ligne par PR, montrant sa tête, son nombre de chemins, son nombre de blobs, et MATCH, ainsi qu'un total. Coller le bloc textuellement dans la description de la PR de lot.

7. Ouvrir la PR de lot en tant que brouillon. Pousser la branche, puis créer le brouillon contre la principale. Le titre indique le nombre de PR réellement livrées, pas le nombre considéré :

   gh pr create --draft --base main --title "docs: land <k> reviewed docs PRs" --body-file <body-file>
   

8. Écrire la description. Inclure une note indiquant que la construction a été sautée pour une différence de documentation uniquement, la liste des PR livrées avec leurs nombres de fichiers et têtes, les PR exclues avec leurs raisons, les indicateurs pour le réviseur, et le bloc de vérification. Relire l'état de la nouvelle PR, et confirmer qu'il s'agit d'un brouillon contre la principale.

Pièges

• Ignorer la règle du brouillon. Les instructions d'une exécution peuvent demander une PR prête pour la révision. L'ouvrir en tant que brouillon sauf si les règles de l'exécution disent le contraire, et le mentionner dans la description.
• Une PR source basée sur une autre branche. Ses fichiers passent toutes les règles de chemin, mais les livrer sur la principale modifie ce que signifie la PR. L'inclure seulement si les règles le permettent, et la signaler avec le commit exact à supprimer.
• Pas de base de fusion. Une recherche de base de fusion peut échouer pour une telle PR, et un diff contre la base génère alors une erreur. Utiliser la liste de fichiers en direct comme source des chemins. Recouper avec un diff contre la base de fusion uniquement là où elle existe.
• Une livraison partielle. Une PR qui modifie des fichiers que la principale a déjà peut être exclue même si ses autres fichiers sont nouveaux. Ne pas livrer une partie de celle-ci.
• Inonder la sortie d'erreurs de chemin manquant. Une vérification qu'un chemin existe sur la principale imprime une erreur pour chaque chemin manquant. Rediriger la sortie d'erreur vers /dev/null dans ces vérifications.
• Gonfler le rapport final. Rapporter la liste des exclus avec les raisons, les indicateurs et les totaux de vérification. Ne pas lister chaque fichier.
• Un graphe ou index manquant. Si un index d'intelligence de code n'est pas disponible pour le dépôt, le mentionner dans le rapport, et ne pas sauter les règles de chemin.

Vérification

• La PR de lot est un brouillon contre la principale.
• Chaque blob de fichier livré correspond à sa tête source, comme indiqué dans le bloc de vérification.
• Aucun fichier modifié ne se trouve en dehors du dossier de documentation.
• Chaque PR exclue a une raison dans la description.
• Les PR sources sont inchangées. Cette procédure ne les a pas fusionnées, approuvées, fermées ou commentées.