Documentation

Learn about all of Crocodile's features.

Table of contents

• Setup

• Adding team members

• Creating your first review

• Reviewing code

  • File browser
  • Code diff
  • Commenting
  • Reviewer status
  • Comparing iterations

• Keyboard shortcuts

• Sync review

• Billing

Setup

Setting up Crocodile takes less than 3 minutes.

1. Go to the setup page.
2. Login with your GitHub account if you haven't already.
3. Click the setup button for the plan you want. There are two options:
   • Setup Crocodile Open Source which is free for public open source repositories.
   • Setup a 30-day free trial of Crocodile Professional which lets you use Crocodile with private repositories. No credit card is required. Accounts will automatically convert to the Open Source plan after the trial ends.
4. After clicking the setup button you'll be directed to GitHub's app installation page. If you are a member of several organizations, you'll be asked to select an organization to install the Crocodile app under.
5. Next select which repositories to install Crocodile on. You can select specific repositories or all repositories. Crocodile will only have access to the repositories you select here. Repositories can be added or removed from GitHub's app settings.

Adding team members

To access a review for a private repostiory, you must have access to the repo in GitHub and be a member of the organization in Crocodile. This means you will need to add your team members to your Crocodile organization in order to collaborate on reviews for private repostories.

To add team members:

1. Go to the organization settings page.
2. Click on the organization you want to invite people to.
3. Click the "Show link" button in the "Add members" section.
4. Copy the membership link and share it with people you want to work with.

Visiting the membership link will give you the option to request to join the organization. When someone requests to join, you will receive an email notification. Requests will be displayed in a table below where you copied the membership link with buttons for approving or denying the request.

Only organization owners can see the membership link and manage join requests.

Creating your first review

Reviews are automatically created whenever you create a pull request. Crocodile will add a comment to the pull request with a link to the review.

Reviewing code

Reviewing code in Crocodile is simple and intuitive. The initial page of the review shows the review description which is synced with the GitHub PR description. Below the description is a button you can use to manually sync the review with the pull request.

File browser

To the left is the file browser where you can select which file to open. Each file also has a checkbox that you can toggle to track which files you've reviewed. The review state is for each file version so if the author modifies a file in a subsequent iteration, the newer file version will be marked as unreviewed.

Clicking a file opens it for review.

Code diff

Clicking on a file in the file browser opens it for review. The main section will show the code diff. The header above the code shows:

• Modification type (add/edit/delete/etc.)
• File name
• Buttons for going to the next or previous modification in the file
• A button to toggle between unified or split diff view

Commenting

You can highlight any piece of text in the code diff and click the "Add comment" that appears next to the selection to add comments. When you add a comment, it appears in a modal window that floats above the code with a line connecting it to the code that was highlighted. This comment modal can be repositioned by dragging the bar at the top of the modal or minimized to the margin but clicking the "_" minimize button.

People can respond to comments by adding messages to it. If you hover over a message, a "..." button will appear which you can click to see options for editing the message if you are the author and for starting a threaded reply.

Each comment starts with an Open status. Anyone can change the status, but here is a suggested workflow:

1. Reviewer adds a comment with an initial status of Open.
2. Author feels like the comment has been addressed and changes the status to Resolved.
3. If the reviewer doesn't think it has been resolved, they can change it back to Open. Otherwise, they change it to Closed to let the author know they are satisfied with the resolution.

Reviewer status

Reviewers can set their status to indicate to several states. The table below describes the intended meaning for each state.

Reviewers can change their status by selecting it from the dropdown and clicking update. The review author is notified whenever a reviewer updates their status. Note that you can update your review status without changing it. This will update the review time and notify the author, which can be useful to let them know you've reviewed the latest changes or responded to comments.

Comparing iterations

A new iteration is created every time the review author pushes new code to the review. Iterations are shown below the file list. Clicking on an iteration will diff the code at that time against the base.

The two columns of radio buttons let you diff two iterations to see what changed between them. The left and right radio buttons correspond to the left and right side of the diff. So if you wanted to see what changed between iterations 3 and 1, then you would select the left radio button of iteration 1 and the right radio button of iteration 3 and click the "Compare selected" button. This is often useful to see just changes that have been made since your last review. The last iteration you reviewed is indicated by the clock icon (iteration 1 in the screenshot).

Keyboard shortcuts

Crocodile has a number of keyboard shortcuts that make navigating reviews a breeze.

With a file selected using the j or k keys:

With a file open:

When adding or replying to a comment with the cursor in the text box:

Sync review

Under normal circumstances, a review in Crocodile is automatically kept in sync with its corresponding pull request in GitHub. However, if GitHub has an incident that causes WebHook delivery failures, the review can become out of sync. To fix this, you can click the "Sync review with pull request" button at the bottom of the review description, which will kick off a job to re-sync the review with the pull request.

Billing

Billing is based on the number of users in your Crocodile organization, which is separate from your GitHub organization. See Adding team members to learn how to add people to your Crocodile organization.

At the end of each billing period, you will be billed for the maximum number of users that were in your organization for that period. Let's say your billing period starts on the 1st and ends on the 30th.

On the 30th, at the end of the billing period, you'll be charged for 4 users since that was the maximum number of users for the period.