diff-système

Que fait diff-système ?

Un diff-système montre ce qu'un changement fait au système en cours d'exécution : les composants et flux qu'il ajoute, supprime ou modifie, les états qu'une chose peut désormais parcourir, les faits qui basculent, et la nouvelle façon dont il peut échouer. Le diff de lignes est la preuve ; le diff-système est l'histoire dont un relecteur a besoin.

Vous modélisez le changement sous forme de spécification, et le script rend la spécification sous forme de vidéo en séquences : titre, avant et après pour chaque diagramme, défaillance, conclusion. Ci-dessous, <script> est le chemin absolu de scripts/system-diff.mjs dans le dossier de ce skill.

1. Vérification de la configuration

Exécutez node <script> doctor. Cela se termine par Prêt. sur une machine configurée.

Sur toute autre fin, ou si node est manquant, arrêtez-vous et demandez à l'utilisateur d'exécuter /setup-system-diff, qui installe tout ce dont ce skill a besoin.

2. Rassembler le changement

Le changement est une pull request, une branche ou une plage de commits. Si rien n'est nommé, prenez la branche courante par rapport à sa base : la branche de base de la pull request si elle en a une, sinon la branche par défaut du dépôt. Demandez à l'utilisateur quand rien n'est clair.

Travaillez dans un checkout qui se trouve à la tête du changement, car l'étape 4 vérifie vos preuves par rapport aux fichiers sur le disque.

• Lisez l'ensemble du diff (gh pr diff <numéro>, ou git diff <base>...<tête>), et la description de la pull request si elle existe, ou les messages de commit sinon.
• Pour chaque bloc qui touche un appel, une requête, un planning, une valeur de configuration, un schéma ou une permission, lisez suffisamment de code autour, à la base et à la tête, pour savoir qui appelle quoi au moment de l'exécution.

Terminé quand vous pouvez dire, pour la base et pour la tête : ce qui s'exécute, à quoi chaque chose parle, ce qu'elle stocke, et ce qui se passe quand chaque chose dont elle dépend est en panne.

3. Modéliser le changement système

Listez le changement sous forme de revendications, chacune avec le chemin:ligne qui le montre. Les revendications deviennent la spécification à l'étape 4 et sont présentées à l'utilisateur à l'étape 6.

• Composants : des choses qui s'exécutent ou stockent des données, comme un service, un job, une file d'attente, une table ou une API externe. Incluez ceux qui n'ont pas changé mais dont le spectateur a besoin pour suivre le flux.
• Flux : un composant qui en appelle, en lit ou en écrit un autre.
• États et transitions : les étapes qu'une chose parcourt, comme une commande, un job, une session ou une connexion, et les événements qui la font passer de l'un à l'autre.
• Faits : une chose sur le système avec une valeur avant et après, comme une valeur de configuration, une limite, un schéma, qui peut faire quoi, ou combien de temps quelque chose prend.
• Mode de défaillance : la nouvelle façon la plus importante d'échouer. Généralement, un nouveau composant ou une nouvelle dépendance s'arrête ; cela peut aussi être un composant existant dont la défaillance coûte désormais plus cher, ou un état dans lequel une chose peut maintenant rester bloquée. Dites ce qui se passe alors : ce que chaque autre composant fait, ou où la chose se retrouve.

Chaque revendication cite la ligne qui la montre. Une revendication sans ligne à citer est une supposition et reste hors de la vidéo.

Certains changements laissent le système tel quel : un refactoring, du formatage, des tests, des commentaires, un renommage de quelque chose que seul le code voit. Pour ceux-ci, dites à l'utilisateur que le changement n'a pas de diff-système et de quel type de changement il s'agit, et arrêtez-vous là sans vidéo. Un renommage de quelque chose que le système en cours d'exécution voit, comme une route, une table, une file d'attente ou une clé de configuration, est un changement système.

Les revendications décident quel diagramme la vidéo dessine :

• Vue des composants, quand le câblage change : un composant ou un flux est ajouté ou supprimé, ou un flux transporte quelque chose de différent.
• Diagramme d'états, quand un cycle de vie change : un statut gagne ou perd une valeur, une étape de nouvelle tentative ou d'annulation apparaît, ou un événement mène désormais ailleurs.
• Une valeur qui change alors que le câblage et le cycle de vie restent les mêmes, comme un délai d'attente plus long, est un fait, affiché sous le diagramme qui lui donne du contexte.
• Les deux, quand les deux changent et que chacun montre quelque chose que l'autre ne peut pas. Chaque diagramme ajoute deux séquences, donc un changement qu'un diagramme raconte en entier n'en obtient qu'un.

Terminé quand chaque bloc du diff est soit couvert par une revendication, soit mis de côté comme ne modifiant pas le système, et que vous avez choisi les diagrammes.

4. Écrire la spécification

Transformez les revendications en une spécification, en suivant SPEC.md, qui contient tous les champs, les règles de disposition et la façon d'écrire les légendes et la narration. Enregistrez-la sous system-diff.json dans un dossier temporaire en dehors du dépôt.

Exécutez node <script> check <spécification> --repo <racine du dépôt>.

Terminé quand cela imprime exactement La spécification est valide., sans avertissements. check confirme que chaque ligne citée existe ; c'est à vous de confirmer que la ligne montre bien la revendication.

5. Construire et lire la planche

Exécutez node <script> build <spécification> --repo <racine du dépôt> --out <dossier temporaire>. Cela imprime le chemin de la vidéo, ses avertissements, une planche de contact (une image avec une image de chaque séquence) et un dossier stills contenant les mêmes images en pleine taille.

Lisez la planche de contact pour la vue d'ensemble et les images individuelles pour le petit texte, et vérifiez chaque image :

• chaque étiquette, valeur et légende est entière et lisible ;
• chaque ligne de flux est dégagée des boîtes et des étiquettes qu'elle ne connecte pas ;
• chaque image "avant" montre seulement ce qui existait avant, et chaque image "après" montre tout ce que le changement a ajouté ;
• le point de départ d'un diagramme d'états se trouve sur l'état où la chose commence ;
• l'image de défaillance marque le bon composant ou état, et chaque note repose sur le bord inférieur de celui qu'elle décrit ;
• chaque légende dit ce que son image montre.

Corrigez la spécification et reconstruisez jusqu'à ce que la construction imprime Aucun avertissement. et que la planche passe toutes les vérifications. La plupart des problèmes d'image cèdent à un texte plus court ou au déplacement d'une boîte vers une autre cellule. Celui qui survit aux deux va dans la remise, nommé.

6. Remettre

Donnez à l'utilisateur le chemin de la vidéo, une phrase sur ce qu'elle montre, les revendications avec leurs preuves, et tout ce que vous avez omis ou dont vous n'étiez pas sûr. Publier la vidéo est la décision de l'utilisateur.