Getting Started

To help you understand how PullReview works, you'll find below the few steps needed to setup PullReview on your project and get your first reviews.

As an example, I've taken the Michael Hartl's very nicely done Rails Tutorial. It is not only a very good introduction to Rails, but also to many useful tools around, notably Git. As Michael's emphasizes good branch usage, it was quite a natural fit for this onboarding guideline.

Note that I suppose that your project already exists in GitHub, even if empty, so I'll start with the tutorial at Chapter 3. I readily encourage you to read the two firsts chapters also!

Setup

Setting up PullReview can be done in three clicks and less than a minute. Let's get it done!

1. Sign-up with GitHub

PullReview ask you for your GitHub login name in order to sign you up. Let's type it in:

2. Authorize PullReview

This will redirect you toward GitHub authorization page. At that time we just need your emails, so we can identify your contributions to your various projects. PullReview will need some additional authorizations (like for private projects) but this is enough for now. We'll also use your primary email to contact you and send you notifications.

Why are we asking those rights?

  • PullReview needs your emails to be able to identify which commits belong to you.
  • PullReview accesses your list of public repositories to let you pick which you want to review.

3. Follow your repository

Once the authorization is done, you'll be redirected to PullReview. As you are not following any repositories, we'll direct you to the repository page.

For now, we only show public repositories. Should you want PullReview to access your private repositories, you'll need one more step.

This is the list of all repositories that you own or collaborate to to organizations you are member of. You can then select any of them to request PullReview to start creating reviews for them.

Note that with those rights, we can just access your public repositories, and are unable to create a webhook to generate a review each time you push. You can either authorize PullReview for more, or put those manually.

Optional: authorize PullReview

Should you want to use PullReview on your private repositories, or have the convenience of having PullReview create webhooks for you, you can click on "authorize".

We require additionnal rights for that, so back to GitHub for authorization. We'll ask for access to either just your public repositories (if you are using a free plan) or public and private if you are going for the paying plan.

Once back to pullreview, you can ask to "sync with GitHub" to see your full list of repositories (including private ones).

Done! Let's start coding!

Your first reviews

This part is closely following the Rails Tutorial, so I'll reference it as much as possible.

Mostly Static Pages

Let's follow the first part of the tutorial. Here we'll create our Rails application, checking the versions of our various gems and creating a secret token for it. I've put a quick summary of my commands in the terminal:

  • gem install rails
  • git clone git@github.com:vanakenm/railstutorial.git
  • rails new railstutorial --skip-test-unit
  • cd railstutorial/
  • bundle install --without production
  • rails g rspec:install
  • git add .
  • git commit -m "Base application initial commit."
  • git push

Once the code is pushed, PullReview webhook will be notifier, and we can go check PullReview:

Looks like there is already one review. The little marker shows that this is an integration branch - as I did not create any feature branch yet, PullReview did a full review of master. Also, it looks like I already have some work to do. Let's click on the review to get the details.

  • No doc is given for the initial ApplicationController
  • Rspec default generator uses double quotes
  • I did not commit any test (I knew that)
  • I manage to miss documenting my very first method #secret_token

Clicking on any of those would show a short explanation about the problem. Let's check this quote thing:

Ok, understood, so let's fix those problems, and let's continue the tutorial.

Static Pages and a first branch

We're now at chapter 3.1 of the Rails Tutorial, which proposes us to create a branch for the next part. I did follow the suggestion, but pushed my branch immediately:

  • git checkout -b feature/static-pages
  • git push

A quick check on PullReview tell me that the branch has been analyzed:

Everything is green as PullReview only check the changes on the branch. Since all problems where preexisting, for now everything is fine. I even get a good point for fixing this missing documentation problem.

PullReview also notified me by email (this can of course be switched off in your settings).

Some more work

I advanced into the tutorial until the 3.3 "Sligthly dynamic pages". I pushed my branch before, and got an almost instant review:

Let's look at it:

OK, looks like a good time to fix some stuff. The double quote is really a style issue, but one I like, so I'll go fix it. The similar code is in my test, and I'm OK with some duplication in the tests, so I'll let go. I forgot again do document, so I'll do that too.

That looks better, now I can go forward. I even got a mail from PullReview congratulating me:

The tutorial next step is all about putting titles. Before going to 3.3.3, I've committed and pushed my changes again. Again two small styles issues quickly committed.

Back to the tutorial to finish the part, and a last push & review cycle. Looks like only the test duplication remains, so I can merge my branch.