Cross-repository reviews

La revue inter-dépôts est ce que les Systèmes rendent possible. Regroupez des dépôts liés en un système, et une revue peut vérifier comment un changement affecte le code dans chaque dépôt que ce système atteint.

Regroupez des dépôts liés en un système et enregistrez leurs connexions afin que les revues puissent suivre ces relations. Ce guide vous montre comment procéder. Pour une introduction aux parties, aux connexions et aux résultats de découverte, voir Systèmes.

Avant de commencer

Les dépôts sont connectés, sur le cloud ou sur votre propre instance.
Vous êtes un owner ou admin de l'espace de travail, ou il s'agit de votre espace personnel. Sans cela, les boutons ci-dessous ne sont pas affichés du tout.

1. Lisez chaque dépôt

Un dépôt n'entre pas dans un système en tant que partie brute. Sa lecture en dérive un système propre, nommé owner/repo, et le système plus vaste est ensuite composé de ces systèmes plus petits.

Ouvrir Systèmes dans la barre latérale. Si rien n'a été modélisé, vous verrez Nothing modelled yet et un bouton Create a system ; sinon, utilisez le bouton + dans l'en-tête, dont l'infobulle indique New system.

Le tiroir s'intitule Draw a system. Près du bas, sous Not read yet, chaque dépôt connecté sans système derrière lui est listé avec un bouton Read it Lisez ceux que vous voulez dans le système.

Vous pouvez aussi le faire depuis la page propre d'un dépôt, où le bouton est Initialize from GitHub, ou Read again s'il a déjà été lu.

2. Créez le système qui les contient

Dans le même tiroir :

Read the repositories, sous What looks like one system, propose des regroupements. Chaque suggestion indique sa provenance : From a declared dependency, From imports across repositories, ou From names only. Elle ne crée rien d'elle-même.
Name le système, par exemple Billing.
What it is: une ligne sur ce qui doit être compris ensemble pour le modifier.
Inside another system: laissez sur Nothing. This is a system of its own sauf si vous l'imbriquez.
Systems in it : cochez les systèmes de référentiels que vous lisez à l'étape 1. Ils font partie intégrante de ce système plutôt que de constituer des systèmes à part entière.
Créer un système.

From names only mérite une lecture attentive. Une suggestion qui ne repose que sur un nom correspondant est la preuve la plus faible qui soit, et c'est celle qu'il vaut le plus la peine de vérifier manuellement.

3. Trouvez les connexions

Ouvrez le système. Cliquez sur l' icône en forme de partage juste à gauche du + bouton dans l'en-tête. Son infobulle est Trouver des connexions: lisez à quoi ces éléments sont rattachés, d'après ce que chacun publie et ce que dit son code. Elle apparaît une fois que le système contient des systèmes de référentiels.

Il lit les référentiels en arrière-plan et indique sa progression, par exemple Lecture des référentiels 3. puis Référentiels 3 lus. Impossible de lire 1. Lorsqu'il a terminé, la page bascule d'elle-même vers l'onglet Parties . Sur un patrimoine important, cela peut prendre plusieurs minutes ; quitter la page n'interrompt pas l'opération.

4. Validez ce qui est réel

Tout ce que trouve l'inférence arrive en attente. Rien de ce qu'elle propose n'est traité comme un fait tant qu'une personne ne l'a pas confirmé.

Trois endroits pour les traiter, tous faisant la même chose :

La carte de triage en haut de la page Systèmes, intitulée N connexions à examiner et ordonnée Preuves les plus faibles en premier. Approuver ou Rejeter chacune.
Le La section Connexions Parties sous chaque système dans l'onglet
Architecture → Interactive, qui ajoute Conserver les N et Tout ignorer pour traiter une pile rapidement.

Travaillez en commençant par les preuves les plus faibles, ce qui correspond déjà à l'ordre de la carte de triage. Une connexion lue à partir d'une dépendance déclarée est généralement correcte. Une connexion reposant sur une correspondance de nom mérite les dix secondes nécessaires pour ouvrir le fichier qu'elle cite.

Ce que change réellement l'approbation

C'est la partie qu'il vaut la peine de comprendre, car elle ne correspond pas à ce que la plupart des gens supposent. Une revue s'étend à un autre référentiel que le lien soit approuvé ou non. L'approbation ne conditionne pas la portée. Elle change la manière dont la revue est autorisée à en parler.

État du lien	Ce que fait la revue
Approuvé	Énonce la portée comme un fait, et indique où la modification pourrait casser l'autre côté.
En attente	Soulève sous forme de question ce que le lien impliquerait. Elle ne l'affirme pas et n'y attache aucune suggestion.

Ainsi, un graphe non approuvé n'est pas défaillant. Il est simplement plus discret. Approuver, c'est indiquer au relecteur qu'il est autorisé à être certain.

5. Lisez une revue

Ouvrez une pull request dans l'un des référentiels. La revue gagne une section sur ce que la modification atteint : les systèmes à l'autre bout, le code frère qu'elle est allée lire, cité avec le référentiel et la révision dont il provient.

Un référentiel frère est lu à la révision de sa dernière indexation, car une pull request n'épingle que la sienne. Lorsque cette révision est ancienne, la revue le signale plutôt que de la présenter comme actuelle.

Ce qu'elle n'a pas pu lire

Un référentiel que la revue n'a pas réussi à atteindre est nommé dans la revue, avec la raison. Il n'est pas discrètement ignoré.

C'est la différence entre un relecteur sur lequel vous pouvez compter et un autre. Un relecteur qui saute silencieusement la moitié de votre système est identique à celui qui a tout lu et n'a rien trouvé.

Les causes habituelles, par ordre de fréquence :

Le référentiel n'a jamais été lu, il n'a donc aucun système derrière lui. Revenez à l'étape 1.
Il est connecté, mais pas au sein du même système.
L'application n'y est pas installée, il n'y a donc rien à récupérer.

Éléments qui ne sont pas des dépôts

Une grande partie de ce dont un système dépend ne comporte aucun code à lire. Dans l'onglet Éléments, développez un système et utilisez + Ajouter pour ajouter une ressource : un service, une base de données, une file d'attente, une API externe, Déploiement, un schéma, un document, ou tout autre élément que vous nommez vous-même.

Donnez-lui un Name et un identifiant, c'est-à-dire le nom sous lequel elle existe là où elle se trouve réellement, afin qu'une personne lisant la revue puisse aller la retrouver.

Relier les éléments à la main

L'inférence ne propose que ce qu'elle peut rattacher à un fichier. Lorsque vous connaissez une liaison qu'elle ne peut pas voir, utilisez Ajouter des connexions dans l'onglet Éléments : sélectionnez De et Vers, puis Comment ils sont reliés. Les choix sont Dépend de, Consomme, Fournit, Expose, Contient, Déploie, Teste et Documents.

Une connexion que vous ajoutez vous-même est approuvée immédiatement. C'est vous qui l'auriez approuvée.

Revue de code : ce à quoi d'autre un changement est confronté.
Knowledge management : les décisions et contraintes qu'une revue lit parallèlement au graphe.
Systèmes et revues inter-dépôts : comment la carte est construite et maintenue fidèle.