Review Map Guide

Review Maps allow you to do a visual, interactive code review. As an author, you can walk your reviewers through your change with a Tour. As a reviewer, you can grasp the entire change at a glance, and review code in logical chunks. (So much better than alphabetical!)

Once Maps is installed on a repository, Review Maps will be automatically generated for every pull request made to the repository. There is also an “Install Review Maps” button on the /maps page to get you up and running.

Generating A Review Map

To get started, make a pull request to the repository.

Once that's done, the codesee-maps bot will automatically comment on your pull request with an image of a Review Map showing the files impacted by the PR, along with a Map Legend. Code is grouped intuitively so that you can review based on logic and functionality. For example, choose to review left to right (general to more specific) or review sections based on type (back-end vs. front-end changes, etc.)

Generated Review Map showing a pull requestGenerated Review Map showing a pull request

Generated Review Map showing a pull request

The Map shows:

  • Green boxes: Files added in this pull request
  • Green lines: Dependencies between files added in this pull request
  • Red boxes: Files removed in this pull request
  • Red lines: Dependencies between files removed in this pull request
  • Orange boxes: Files that have been modified in this pull request
  • White boxes: Files that are unchanged, but have a changed file as a dependency. These are files that may be impacted by this pull request.

If new commits are added to a pull request, the Review Map will update automatically.

Interacting With A Review Map

There are two ways to navigate to your Review Map and start a visual code review:

  1. Click on the image in the github pull request.
  2. Navigate to app.codesee.io/reviews and click on the correct pull request. (By the way, on this page you can see all your pull requests across all connected repositories!)

Click on a file to highlight its connections. Double-click to view related code (more details below). Expand and collapse folders using the arrow icons. Or zoom into and out of the Review Map by using the Zoom UI.

To access PR-related details during the review, look to the header at the top of the page. Then,

  • Click the PR title or number to navigate to that PR in GitHub.
  • Click the PR author to visit that user’s page in GitHub.

Code Diffs

Double-click on individual nodes in a Map to view code in a diff format. Each file gets a color swatch that indicates whether the file was added, removed, edited, renamed, or is unchanged.

Double-clicking on an “unchanged” file (the white nodes on the Map) will also display their code.

When viewing a file, any related files (files it imports, and files that import it) that remain unchanged will also be listed in the diff. Unchanged files start with all their code hidden, but can be displayed by clicking on a file header to expand/collapse that file.

To return to the full Review Map, click on the back arrow in the header.

Progress Bar

Mark sections as 'Reviewed' via the checkboxes as you move through the code review. When the checkbox is selected, nodes on the Map are displayed as “Reviewed,” and files within the diff collapse. A progress bar indicating the number of files in the PR that have been reviewed is visible in the header.

Comments

Provide feedback on reviews by placing and responding to comments. You can add comments on specific lines within the code diffs or in the pull request discussion within the side panel. Comments are instantly reflected in both the repository and in CodeSee.

Discussion in a pull requestDiscussion in a pull request

Tip: you can leave comments that span multiple lines by dragging the "new comment" button up and down:

Once a code review conversation is resolved, click "Resolve conversation" to collapse the thread. You can always bring it back by expanding the thread again and clicking on "Unresolve conversation":

Resolve a conversationResolve a conversation

Mark files as viewed

When performing a code review, it can be helpful to note files that have undergone review to keep track of progress. When viewing a file diff, click the checkbox on the top right to mark the file as "Reviewed":

Interact with a Review MapInteract with a Review Map

Review Map Settings

The Review Map settings can be accessed using the menu on the right side:

Gif of accessing the Review Map settingsGif of accessing the Review Map settings

By default, all the connections between files and directories are displayed on a Review Map. To reduce visual clutter, turn on the "Hide links between files" setting. In this mode, you can still select files and directories to see the incoming and outgoing connections.

Setting to toggle the visibility of links in Review MapsSetting to toggle the visibility of links in Review Maps

The layout of a Review Map is automatically generated. However, we've introduced an experimental flag that allows users to reposition files and directories by dragging them around the page.

Setting to toggle the ability to reposition nodes in Review MapsSetting to toggle the ability to reposition nodes in Review Maps

Submit A Code Review

Click the “Review” button in the header to make a final review comment approving, requesting changes, or commenting on the pull request.

Submit review on pull request via a Review MapSubmit review on pull request via a Review Map

Permissions

On a public repository, logged-out users or users without a CodeSee account can view a Review Map. However, users looking to comment or submit a review will be prompted to log in.

On a private repository, logged-out users or users without a CodeSee account cannot view a Review Map. The user will be prompted to log in or sign up to view the Review Map.


What’s Next