SourceAnt

Cross-repository reviews

Cross-repository review is what Systems makes possible. Group related repositories into a system, and a review can check how a change affects the code in every repository that system reaches.

Group related repositories into a system and record their connections so reviews can follow those relationships. This guide shows you how to set that up. For an introduction to parts, connections and discovery results, see Systems.

Before you start

  • The repositories are connected, on the cloud or on your own instance.
  • You are an owner or admin of the workspace, or it is your personal one. Without that the buttons below are not rendered at all.

1. Read each repository

A repository does not go into a system as a bare part. Reading it derives a system of its own, named owner/repo, and the bigger system is then made of those smaller ones.

Open Systems in the sidebar. If nothing has been modelled you will see Nothing modelled yet and a Create a system button; otherwise use the + in the header, which is tooltipped New system.

The drawer is titled Draw a system. Near the bottom, under Not read yet, every connected repository with no system behind it is listed with a Read it button. Read the ones you want in the system.

You can also do this from a repository's own page, where the button is Initialize from GitHub, or Read again if it has been read before.

2. Create the system that holds them

In the same drawer:

  1. Read the repositories, under What looks like one system, proposes groupings. Each suggestion says where it came from: From a declared dependency, From imports across repositories, or From names only. It creates nothing on its own.
  2. Name the system, for example Billing.
  3. What it is: one line on what has to be understood together to change it.
  4. Inside another system: leave it on Nothing. This is a system of its own unless you are nesting it.
  5. Systems in it: tick the repository systems you read in step 1. They become part of this system rather than systems of their own.
  6. Create system.

From names only is worth reading carefully. A suggestion resting on nothing but a matching name is the weakest evidence there is, and it is the one most worth checking by hand.

3. Find the connections

Open the system. Click the share-shaped icon just to the left of the + button in the header. Its tooltip is Find connections: read what these are joined to, from what each one publishes and what its code says. It appears once the system has repository systems inside it.

It reads the repositories in the background and reports progress, for example Reading 3 repositories. then Read 3 repositories. 1 could not be read. When it finishes the page moves itself to the Parts tab. On a large estate it can take several minutes; leaving the page does not stop it.

4. Approve what is real

Everything inference finds arrives pending. Nothing it proposes is treated as fact until a person says so.

Three places to work through them, all doing the same thing:

  • The triage card at the top of the Systems page, headed N connections to look at and ordered Weakest evidence first. Approve or Reject each one.
  • The Connections section under each system on the Parts tab.
  • Architecture → Interactive, which adds Keep all N and Dismiss all for working through a pile quickly.

Work weakest-evidence-first, which is the order the triage card already puts them in. A connection read from a declared dependency is usually right. One resting on a name match deserves the ten seconds it takes to open the file it cites.

What approving actually changes

This is the part worth understanding, because it is not what most people assume. A review crosses into another repository whether or not the link is approved. Approval does not gate the reach. It changes how the review is allowed to talk about it.

Link stateWhat the review does
Approved States the reach as fact, and says where the change could break the other side.
Pending Raises what the link would mean as a question. It does not assert it, and it attaches no suggestion to it.

So an unapproved graph is not a broken one. It is a quieter one. Approving is how you tell the reviewer it is allowed to be certain.

5. Read a review

Open a pull request in one of the repositories. The review gains a section for what the change reaches: the systems on the other end, the sibling code it went and read, quoted with the repository and the revision it came from.

A sibling repository is read at the revision it was last indexed, because a pull request pins only its own. Where that revision is old, the review says so rather than presenting it as current.

What it could not read

A repository the review failed to reach is named in the review, with the reason. It is not quietly skipped.

That is the difference between a reviewer you can rely on and one you cannot. A reviewer that silently skips half your system looks identical to one that read everything and found nothing.

The usual causes, in order of how often they turn out to be the answer:

  • The repository was never read, so it has no system behind it. Go back to step 1.
  • It is connected but not inside the same system.
  • The app is not installed on it, so there is nothing to fetch.

Parts that are not repositories

Plenty of what a system depends on has no code to read. On the Parts tab, expand a system and use + Add to add A resource: a Service, Database, Queue, External API, Deployment, Schema, Document, or something else you name yourself.

Give it a Name and an Identifier, which is what it is called where it actually lives, so somebody reading the review can go and find it.

Joining things by hand

Inference only proposes what it can point at a file for. When you know about a joint it cannot see, use Add connections on the Parts tab: pick From and To, then How they are joined. The choices are Depends on, Consumes, Provides, Exposes, Contains, Deploys, Tests and Documents.

A connection you add yourself is approved immediately. You are the person who would have approved it.

Next