In week one you added one file to the class roster and it went in through a pull request. That was the smallest possible change, in a shared repository, with the computer refusing to let anyone skip the review. From here on the change is a feature, the repository is yours, and nobody enforces the rule but you. The steps are the same.

1. Start from a ticket

A ticket is a GitHub issue: a short story about who wants what and why, and under it a definition of done, a few sentences that say when the feature is finished. In the class repo the tickets are already in the Issues tab. For your own project you write them: one issue per feature, three to five checkable sentences each.

Read the ticket before you touch anything. It is what your reviewer will hold the change against.

2. Branch first

Never build on main. In the bottom-left corner of the Codespace, click main, choose Create new branch, type posts-form, and press Enter. The corner now reads posts-form, and everything you commit from here goes on that branch. (Source Control's ... menu has the same thing under Branch, Create Branch.)

The name describes the change. If you forget and commit on main, nothing is lost: make the branch now the same way, and your commit comes with it.

3. Build it, with tests

Before the prompt, one line in AGENTS.md, the file your agent reads before it does anything. It already says that every sentence of a definition of done gets a test, and it points at the code rules; the agent already knows how to read a GitHub issue. Add the one thing nobody said, at the end of the Rules list:

- After changing any code, run the tests and report the result before saying you are done.

Then the prompt can be short, because the file carries the rest:

Read issue #1 and build it.

Watch what happens that you did not ask for: the agent reads the ticket, writes one named test per sentence, runs them and reports. That is what the file is for. Anything you would otherwise type into every prompt belongs there instead.

Then check it yourself, twice: use the page in the browser, and run the tests:

bin/rails test

Open the test file and read the test names against the ticket. One per sentence? A sentence with no test is a sentence nobody checked.

4. Commit and publish

In Source Control, stage the changes and commit with a message that says what changed, so that someone reading the history later knows without opening the diff. "Add the new post form and create action, with tests" is a message. "done" and "tried again" are not.

Then Publish Branch. Your branch is now on GitHub; main is untouched.

5. Open the pull request

On your repo's GitHub page a banner offers Compare & pull request. Click it. The title is the ticket's title. In the body, write closes #1 (the issue number), so merging the PR closes the ticket, and a sentence on what you did. Create pull request.

A pull request is a request to change main. Nothing has changed yet.

6. Invite your reviewer

Your copy of the repo is private, so only a collaborator can review it. On the repo page: Settings, Collaborators, Add people, your partner's GitHub username, Add. They accept from the email GitHub sends, or at github.com/notifications.

7. Review someone else's

Open their pull request. Read the issue it closes, then click Files changed and read the diff. If you are sitting next to them, run the tests on their machine:

bin/rails test

Then answer five questions:

1. Does the change do what the issue says? Read the issue, then the diff.
2. Does the commit message tell you what changed without opening the diff?
3. Does it follow the pattern? The right actions in the right controller, the form posts to the resource's path, create redirects.
4. Is there a test for every sentence in the issue, and do they pass when you run them?
5. Would you merge it? If not, what would you ask for?

The first, second and fifth are week one's three questions. They never change. The third and fourth are new because the change is code now, built against a pattern and a ticket.

Leave at least one comment on a line: hover over a line in the diff, click the blue +, write it, Add single comment. Then Review changes. If all five answers are yes, Approve. If not, Request changes and say which question failed. Submit review.

8. Merge

When your reviewer approves, Merge pull request, Confirm merge, Delete branch. The feature is on main, and the issue it closed is closed.

The merge button worked before anyone reviewed. On a personal repo, GitHub does not stop you. The rule held because you held it. On a team, the repository is set up so the computer holds it too, which is what the roster did in week one.

If you requested changes

The author fixes it on the same branch, commits, and syncs. The pull request updates on its own. Review again. That loop, change, review, change, merge, is the part of this course that carries the furthest, and the one an agent cannot do for you: someone who did not write the code has to read it.

The ticket

Issue #1 in your copy of web-apps-2:

Post a taco
As a Tacostagram user, I want to post a photo of my tacos with a caption, so everyone can see what I'm eating.

Definition of done

• The new post page shows a form with fields for the author, the body and the image.
• Submitting the form creates a post with the author, body and image that were entered.
• After submitting, the user lands on the posts page and sees the new post there.

The ticket is the whole specification. Your agent read it, built it, and wrote one test per sentence. Yours will not match this line for line, and should not. What should match is the shape: two actions, one form, three tests, and a pull request that a classmate reviewed against the ticket.

What the agent built

The controller

new and create were already there as comments. The agent filled them in, keeping each step comment:

def new
  # render posts/new view, the form for a new Post
  render({ :template => "posts/new" })
end

def create
  # start with a new Post
  post = Post.new
  # assign the form's values to the Post's columns
  post["author"] = params["author"]
  post["body"] = params["body"]
  post["image"] = params["image"]
  # save the Post row
  post.save
  # redirect the user
  redirect_to("/posts")
end

new only renders the form. create has no view: it saves and sends the user to a page that already exists. The three keys in params are the three name attributes in the form below.

The form

app/views/posts/new.html.erb had a skeleton with a comment where the fields go:

<h1>New post</h1>

<form action="/posts" method="post">
  <p>
    <label for="author">Author</label>
    <input type="text" name="author" id="author">
  </p>
  <p>
    <label for="body">Body</label>
    <input type="text" name="body" id="body">
  </p>
  <p>
    <label for="image">Image</label>
    <input type="text" name="image" id="image">
  </p>
  <button>Post it</button>
</form>

<p><a href="/posts">Back to all posts</a></p>

action="/posts" and method="post" are the create row of the pattern. No routes were added: resources("posts") in config/routes.rb already made all seven.

The tests

One per sentence, named with the sentence, in test/integration/posts_page_test.rb:

require "test_helper"

class PostsPageTest < ActionDispatch::IntegrationTest
  test "The new post page shows a form with fields for the author, the body and the image." do
    get("/posts/new")

    assert_response(:success)
    assert_select("form[action='/posts'][method='post']") do
      assert_select("input[name='author']")
      assert_select("input[name='body']")
      assert_select("input[name='image']")
    end
  end

  test "Submitting the form creates a post with the author, body and image that were entered." do
    post("/posts", :params => {
      "author" => "Ben",
      "body" => "Al pastor on a Tuesday",
      "image" => "https://images.unsplash.com/photo-tacos"
    })

    created = Post.find_by({ "author" => "Ben" })
    assert_not_nil(created)
    assert_equal("Al pastor on a Tuesday", created["body"])
    assert_equal("https://images.unsplash.com/photo-tacos", created["image"])
  end

  test "After submitting, the user lands on the posts page and sees the new post there." do
    post("/posts", :params => {
      "author" => "Ben",
      "body" => "Al pastor on a Tuesday",
      "image" => "https://images.unsplash.com/photo-tacos"
    })

    assert_redirected_to("/posts")
    follow_redirect!
    assert_select("h3", "Ben")
    assert_select("p", "Al pastor on a Tuesday")
    assert_select("img[src='https://images.unsplash.com/photo-tacos']")
  end
end

bin/rails test
3 runs, 21 assertions, 0 failures, 0 errors, 0 skips

Read each test against its sentence. The first fetches the form page and looks for the three inputs. The second submits the form and looks the row up in the table. The third submits, follows the redirect, and looks for the post on the page. Each one checks exactly what its sentence says, and nothing it doesn't.

Reviewing it

The five questions from class, answered for this change:

1. Does it do what the issue says? The three sentences are the three tests, and they pass.
2. Does the commit message tell you what changed? Yours to judge. "Add the new post form and create action, with tests" would.
3. Does it follow the pattern? new and create in PostsController, the form posts to /posts, create redirects. Yes.
4. A test per sentence, passing when you run them? Three sentences, three tests, green.
5. Would you merge it? Yes. One thing you might ask for: the image is a text box the user has to paste an address into. That is what the ticket asked for; a file upload is week ten.

Issue #2, if you got to it

"Add a contact to a company" is the same loop with one new piece: the company's id has to travel from the company's page, through the form, to create, without the user typing it. That is a hidden field, and the "Handling relationships" section of Creating new records walks through it.

A browser asks for an address, and a server sends back HTML. That's the whole of the web, and it hasn't changed since 1992. This post follows one request through a Rails app: the address you type, the three files Rails reads to answer it, and the page that comes back.

Addresses, host names and paths

The thing in your browser's address bar is a URL (Uniform Resource Locator). Every URL has the same parts, which is the "uniform":

• the protocol, https
• the colon-slash-slash, ://
• the host name, like entr451.com
• the path, like /tacos

The "locator" part means each address points at one thing, one resource. You'd expect these two addresses to show a page about books and a page about shoes:

https://YourDomainName.com/books
https://YourDomainName.com/shoes

While you build, the protocol is always https, and the host name is the long address your Codespace gives port 3000. So from here on we only talk about the path. When this post says /tacos, it means "add /tacos to the end of the address in that browser tab."

The one route that's already there

Open config/routes.rb in your copy of web-apps. Ignoring the comment, it has one line:

Rails.application.routes.draw do
  get("/data", { :controller => "data", :action => "show" })
end

Read it as a sentence: when someone asks for /data, run the show action of the data controller. That line points at two more files:

• app/controllers/data_controller.rb, a class with a method named show. The method decides what to show.
• app/views/data/show.html.erb, the page itself.

Visit /data and you see every table in the database and its rows. That's three files in three folders, and every page in a Rails app is the same three: a route, a controller, a view. Now we'll write a page of our own: a page about tacos, naturally.

Don't fear the error

The route. Add a line under the data line:

Rails.application.routes.draw do
  # get("/things", { :controller => "things", :action => "index" })

  get("/data", { :controller => "data", :action => "show" })
  get("/tacos", { :controller => "tacos", :action => "index" })
end

Save, and visit /tacos. An error:

uninitialized constant TacosController

Error pages in Rails are loud and scary. Don't be afraid of them. They're there to help, and they often say exactly what to do next, if you stop and read them. This one says that Rails read your route, went looking for a tacos controller, and didn't find one. So that's the next file.

The controller. Rails has a command that makes it. In a terminal other than the one running the server, run it with the name from the route:

bin/rails generate controller tacos

It makes two things: the file app/controllers/tacos_controller.rb, and an empty folder, app/views/tacos/, which is where the view will go. You could type the file yourself, but the generator puts the file and the folder exactly where Rails looks for them, named the way it expects. Open the file:

class TacosController < ApplicationController
end

An empty class. Refresh, and Rails says what's missing:

The action 'index' could not be found for TacosController

The route asked for the index action, and an action is a method in the controller. Add it:

class TacosController < ApplicationController
  def index
    render({ :template => "tacos/index" })
  end
end

The class name matches the route's :controller, and the method name matches its :action. The method has one job tonight: show the template tacos/index. Refresh. Another error, and we're still not afraid:

Missing template tacos/index

Rails found the controller, ran index, and went looking for the view. The next file.

The view. Make app/views/tacos/index.html.erb, in the folder the generator made. The folder matters: it's app/views/tacos/, not app/views/. Put some HTML in it:

<h1>Tacos</h1>
<p>Every filling on the menu.</p>
<ul>
  <li>carnitas</li>
  <li>al pastor</li>
  <li>barbacoa</li>
</ul>

Refresh, and there's the page. No more errors.

You didn't have to stop and start the server for any of this. Rails reads your files again on every request, so the next refresh always shows the latest save.

Each of those errors was Rails telling you where it got to. The route sends it to a controller, the controller runs an action, the action sends it to a view, and the error names the first piece that isn't there yet. That's worth remembering the next time a page doesn't work: refresh, read the error, make the piece it names.

Where the rest of the HTML came from

Right-click the tacos page and choose View Page Source. You'll find something like this:

<!DOCTYPE html>
<html>
  <head>
    <title>web-apps</title>
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <meta name="csrf-param" content="authenticity_token" />
    <meta name="csrf-token" content="..." />
    <link rel="stylesheet" href="/assets/application-....css" />
  </head>

  <body>
    <h1>Tacos</h1>
    <p>Every filling on the menu.</p>
    <ul>
      <li>carnitas</li>
      <li>al pastor</li>
      <li>barbacoa</li>
    </ul>
  </body>
</html>

Whoa. We only typed what's inside <body>. The rest comes from
app/views/layouts/application.html.erb, the application layout. Every page in an app shares the same outer shell (the DOCTYPE, <html>, <head>), so Rails keeps it in one file and puts each view inside it, where the layout says <%= yield %>.

What's next

That was a long way to get what a plain HTML file gives you. But every piece is now in place: an address, a route, a controller and a view. A view isn't only HTML, though. Its file name ends in .erb, and that's the next post: Two great things, HTML and Ruby in the same file.

Fell behind in class? code-along-complete/1-tacos/ in your copy has all three files, at the same paths as yours.

The problem

From the Practice section of the web-apps README:

Cards. Make a page at /cards that deals a five-card hand from a shuffled deck, a new hand every time the page loads. Build the deck from these two arrays:

ranks = [2, 3, 4, 5, 6, 7, 8, 9, 10, "Jack", "Queen", "King", "Ace"]
suits = ["Clubs", "Diamonds", "Hearts", "Spades"]

Show each card's name ("Queen of Hearts"). Then show its picture: public/images/cards/ has one per card, named like queen_of_hearts.svg, and the page can show it with <img src="/images/cards/queen_of_hearts.svg">. Add a link that deals again.

You've dealt this hand before, in lab 5 of ruby-intro. That time it went to the terminal with puts; this time it goes on a page.

1. The route and the controller

get("/cards", { :controller => "cards", :action => "index" })

bin/rails generate controller cards

class CardsController < ApplicationController
  def index
    render({ :template => "cards/index" })
  end
end

2. The deck

A loop inside a loop: for every rank, every suit. That's 13 times 4, 52 cards. Start with an empty array and push each card onto it:

<% ranks = [2, 3, 4, 5, 6, 7, 8, 9, 10, "Jack", "Queen", "King", "Ace"] %>
<% suits = ["Clubs", "Diamonds", "Hearts", "Spades"] %>
<% deck = [] %>
<% for rank in ranks %>
  <% for suit in suits %>
    <% card = { "name" => "#{rank} of #{suit}", "image" => "#{rank}_of_#{suit}".downcase } %>
    <% deck.push(card) %>
  <% end %>
<% end %>

Each card needs two things: a name to show ("Queen of Hearts") and the name of its picture (queen_of_hearts). They differ in two ways, the spaces and the capital letters, so a hash holds both, the way a row from the database holds its columns. card["name"] and card["image"] read them the way company["name"] did.

"#{rank}_of_#{suit}" is "Queen_of_Hearts"; .downcase makes it "queen_of_hearts", the file's name. A number works too: "#{10}_of_Clubs".downcase is "10_of_clubs".

3. Shuffle, then deal five

<% hand = deck.shuffle[0, 5] %>

shuffle gives back the deck in a random order. [0, 5] takes five cards, starting from the first. Every refresh is a new request, so the view runs again and the deck is shuffled again.

This is why the hand comes from a shuffled deck, instead of picking five cards with rand the way the dice did: a deck has one Queen of Hearts. Five rand picks could pick the same card twice; five cards off the top of a shuffled deck can't. Two dice can match. Two cards in one hand can't.

4. The hand on the page

<h1>Cards</h1>
<p>
  <% for card in hand %>
    <img src="/images/cards/<%= card["image"] %>.svg" width="100" alt="<%= card["name"] %>">
  <% end %>
</p>
<ul>
  <% for card in hand %>
    <li><%= card["name"] %></li>
  <% end %>
</ul>
<a href="/cards">Deal again</a>

The alt text is what a screen reader says for the picture, and what the browser shows if the picture can't load. The card's name is exactly right for it.

The whole view

<% ranks = [2, 3, 4, 5, 6, 7, 8, 9, 10, "Jack", "Queen", "King", "Ace"] %>
<% suits = ["Clubs", "Diamonds", "Hearts", "Spades"] %>
<% deck = [] %>
<% for rank in ranks %>
  <% for suit in suits %>
    <% card = { "name" => "#{rank} of #{suit}", "image" => "#{rank}_of_#{suit}".downcase } %>
    <% deck.push(card) %>
  <% end %>
<% end %>
<% hand = deck.shuffle[0, 5] %>
<h1>Cards</h1>
<p>
  <% for card in hand %>
    <img src="/images/cards/<%= card["image"] %>.svg" width="100" alt="<%= card["name"] %>">
  <% end %>
</p>
<ul>
  <% for card in hand %>
    <li><%= card["name"] %></li>
  <% end %>
</ul>
<a href="/cards">Deal again</a>

That's a lot of Ruby for a view. It works, and for one page it's fine. Next week, Ruby that works something out moves into the controller, and the view goes back to mostly showing it.

When it went wrong

• Broken images. The file name: lowercase, underscores, .svg on the end. View the page source and compare one src with a file name in public/images/cards/.
• The same card twice in a hand. Five rand picks instead of one shuffled deck.
• 52 cards on the page. The loop over deck instead of hand.
• "Queen of Hearts" in the image name. The name used where the image belongs: spaces and capitals, so no file matches.

The problem

From the Practice section of the web-apps README:

Contacts. Make a page at /contacts that lists every contact's first and last name and the name of their company. Look the company up with Company.find_by({ "id" => contact["company_id"] }). Then add each contact's email.

It's the companies page from class, with one new thing: a contact doesn't hold its company's name, only its company's id.

1. The route and the controller

In config/routes.rb, under the companies line:

get("/contacts", { :controller => "contacts", :action => "index" })

In the terminal that isn't running the server:

bin/rails generate controller contacts

And the action, in app/controllers/contacts_controller.rb:

class ContactsController < ApplicationController
  def index
    render({ :template => "contacts/index" })
  end
end

The errors on the way are the tacos ones: no controller, unknown action, missing template.

2. Every contact's name

app/views/contacts/index.html.erb. The same loop as the companies page, over Contact.all:

<h1>Contacts</h1>
<ul>
  <% for contact in Contact.all %>
    <li><%= contact["first_name"] %> <%= contact["last_name"] %></li>
  <% end %>
</ul>

Four names: Tim Cook, Craig Federighi, Andy Jassy, Dario Amodei.

3. The company, by its id

Open /data and look at the contacts table. Tim Cook's company_id is 1, and the company whose id is 1 is Apple. So for each contact, find the company whose id is that contact's company_id:

<% company = Company.find_by({ "id" => contact["company_id"] }) %>

find_by gives back one row, the first that matches, so company["name"] is its name. It goes inside the loop, because each contact has its own company:

<h1>Contacts</h1>
<ul>
  <% for contact in Contact.all %>
    <% company = Company.find_by({ "id" => contact["company_id"] }) %>
    <li>
      <%= contact["first_name"] %> <%= contact["last_name"] %>, <%= company["name"] %>, <%= contact["email"] %>
    </li>
  <% end %>
</ul>

The email was the last step: contact["email"], one more cell of the same row.

Tim Cook, Apple, tim@apple.com
Craig Federighi, Apple, craig@apple.com
Andy Jassy, Amazon, andy@amazon.com
Dario Amodei, Anthropic, dario@anthropic.com

What the log shows

Refresh the page and look at the bottom of log/development.log. One SELECT for the contacts, then one more for each contact's company, with a WHERE "companies"."id" = ? in it: five lines in all. The second Apple one starts with CACHE: Craig's company is Tim's, and Rails remembered the answer from a moment before, inside the same request. Every other find_by is its own trip to the database. For four contacts that's nothing. For four thousand it would be slow, and later in the course you'll see ways to ask for all of it at once. For now, the point is that you can read exactly what your page asked the database for.

When it went wrong

• undefined method '[]' for nil. find_by found nothing, so company is nil. Usually a typo in the column: "company_id", with the underscore. (Or a contact whose company was deleted.)
• Every contact shows the same company. The find_by line is above the loop instead of inside it.
• company.name instead of company["name"]. It works, but stay with the brackets: a row is read the same way everywhere in this course, column name in brackets.

The problem

From class:

1. A route for /dice in config/routes.rb.
2. bin/rails generate controller dice, then an index action in it.
3. An index view in app/views/dice/.
4. In the view, roll two dice. Show both, and the total.

One die: rand(1..6). Challenge: the pictures, <img src="/images/dice/1.svg">. 1.svg to 6.svg are already in public/images/dice/.

Done? Check your page against your three sentences.

Before you built it, you wrote three sentences that would tell you the page works. Keep them next to you: the last section checks the page against them.

This is the tacos page again, with Ruby doing more of the work. Same three files, same errors, in the same order.

1. The route

In config/routes.rb, under the tacos line:

get("/dice", { :controller => "dice", :action => "index" })

Visit /dice: "uninitialized constant DiceController". Rails read the route and went looking for a controller called dice.

2. The controller

In the terminal that isn't running the server, with the name from the route:

bin/rails generate controller dice

It makes app/controllers/dice_controller.rb, an empty class, and the empty folder app/views/dice/. Refresh: "The action 'index' could not be found for DiceController". The route asked for index, and an action is a method. Add it:

class DiceController < ApplicationController
  def index
    render({ :template => "dice/index" })
  end
end

Refresh: "Missing template dice/index". One file to go.

3. The view, with numbers first

Make app/views/dice/index.html.erb, in the folder the generator made. Roll each die once, at the top, and keep the result in a variable:

<% die1 = rand(1..6) %>
<% die2 = rand(1..6) %>
<h1>Dice</h1>
<p>
  You rolled <%= die1 %> and <%= die2 %>, for a total of <%= die1 + die2 %>.
</p>

rand(1..6) is a whole number from 1 to 6, picked at random. The variables matter: if you wrote rand(1..6) straight into the sentence, the total would come from two new rolls, not the two on the page. Roll once, then use the variables everywhere.

<% %> runs the Ruby and shows nothing; <%= %> runs it and puts the result on the page.

Refresh a few times. Every refresh is a new request, so the view runs again from the top and rolls again.

4. The pictures

The images are named for their number, 1.svg to 6.svg. So the number goes inside the file name:

<p>
  <img src="/images/dice/<%= die1 %>.svg" width="100">
  <img src="/images/dice/<%= die2 %>.svg" width="100">
</p>

When die1 is 4, Rails writes <img src="/images/dice/4.svg">, and the browser asks for that picture. The path starts with /images, not /public/images: everything in public/ is served from the top of the site.

5. Roll again

A link back to the same page asks for it again, which rolls again:

<a href="/dice">Roll again</a>

The whole view

<% die1 = rand(1..6) %>
<% die2 = rand(1..6) %>
<h1>Dice</h1>
<p>
  <img src="/images/dice/<%= die1 %>.svg" width="100">
  <img src="/images/dice/<%= die2 %>.svg" width="100">
</p>
<p>
  You rolled <%= die1 %> and <%= die2 %>, for a total of <%= die1 + die2 %>.
</p>
<a href="/dice">Roll again</a>

Check it against your sentences

Three that the room came up with, and how to check each one by looking at the page:

• Each die shows a number from 1 to 6. Refresh ten times. You should never see a 0 or a 7.
• The total is the sum of the two dice. Add them in your head, every refresh.
• A link rolls again. Click it; the dice change (most of the time: two rolls can match).

If one of yours was "it looks good" or "it's random", try rewording it into something you could count or compare. "It's random" is hard to check by looking once; "the dice aren't the same every time I refresh" is easy.

When it went wrong

• The same roll every time. A number typed where rand(1..6) belongs.
• A broken image. The path: /images/dice/3.svg, with the slash at the front and no public/.
• The total doesn't match the dice. rand(1..6) written into the sentence instead of the variables, so the total rolled its own dice.
• The generator did nothing. It was typed into the terminal running the server, which isn't taking commands. Use the other one.

For a slower walk through the same page, with the tacos page before it, see
Two Great Things.

Migrations showed how a table is born: bin/rails generate model, columns inside create_table, then bin/rails db:migrate. This is the next thing that happens to every table: a column it needs that wasn't there on day one.

The problem

Your movies table is made and migrated, and your tests are green. Now a new story says every movie has a director, and there is no column for it.

The migration that created the table has already run, and Rails won't run it again. Editing it changes nothing in the database, and it leaves a file that lies about what happened. So the rule from Migrations still holds: never edit a migration you have run.

The fix is not to start over. It is one more migration, one that changes the table instead of creating it.

The new migration

Ask Rails for an empty migration. The name says what it does; Rails only needs it to be unique.

bin/rails generate migration AddDirectorToMovies

That makes a new file in db/migrate/, with a newer timestamp than the one that created the table, so it runs after it. Open it. Its change method is empty. Put one line in it:

class AddDirectorToMovies < ActiveRecord::Migration[8.1]
  def change
    add_column :movies, :director, :string
  end
end

add_column takes the table, the new column and its type: the same types as before, :string for text and :integer for numbers and ids. Then run it:

bin/rails db:migrate

Open db/schema.rb. The movies table now lists director. You didn't write that line; Rails did, from the migration. The rows you already had are still there, each with an empty director until something fills it in.

What it does to your tests

Nothing, until a rule says the column matters. The moment your definition of done says "a movie can't be saved without a director" and the model gets that rule, the tests you already had start to react. Any test that saved a movie on its way to checking something else is now saving one with no director, and what happens next depends on what that test was checking. Read each failure for what the test was relying on, and ask whether any test is now passing for a reason other than its own rule. That is not the tests breaking; that is the tests doing their job. Each of those movies now has to be given a director, the way the real app would. When you ask your agent for the new tests, expect it to touch the old ones too, and read what it changed.

The other direction

A column that should go away is the same shape, with remove_column:

remove_column :movies, :director, :string

A new migration, never an edit to an old one. The database's history is the list of files in db/migrate/, in order, and db/schema.rb shows the database's state up to the most recently executed (i.e. ran) migration.

Week 2 had a WHERE. Week 3 had a foreign key: a column in one table that holds the id of a row in another. Code-along 5 is those two ideas in Ruby, and nothing more. A contact works at one company; the contacts table holds that company's id; and you find a contact's company, or a company's contacts, by looking the id up.

Two tables, one column between them

The rules under Contact in DONE.md:

## Contact
A contact can't be saved without a company.
I can find all the contacts at a company: Apple has three.

The prompt asked the agent for the model and its migration as well as the tests, so the migration came first:

class CreateContacts < ActiveRecord::Migration[8.1]
  def change
    create_table :contacts do |t|
      t.string "first_name"
      t.string "last_name"
      t.string "email"
      t.integer "company_id"

      t.timestamps
    end
  end
end

company_id is an integer because it holds another table's id. On the Data page, every contact's company_id is the id of a row in companies. That column is the whole relationship. There's no other link anywhere.

The tests

require "test_helper"

class ContactTest < ActiveSupport::TestCase
  # One test for each sentence under Contact in DONE.md, named with that sentence.

  test "a contact can't be saved without a company" do
    contact = Contact.new
    contact["first_name"] = "Tim"
    contact["last_name"] = "Cook"
    contact.save

    assert_equal 0, Contact.all.count
  end

  test "I can find all the contacts at a company: Apple has three" do
    apple = Company.new
    apple["name"] = "Apple"
    apple.save

    amazon = Company.new
    amazon["name"] = "Amazon"
    amazon.save

    for first_name in ["Tim", "Craig", "Lisa"]
      contact = Contact.new
      contact["first_name"] = first_name
      contact["company_id"] = apple["id"]
      contact.save
    end

    contact = Contact.new
    contact["first_name"] = "Andy"
    contact["company_id"] = amazon["id"]
    contact.save

    apple_contacts = Contact.where({ "company_id" => apple["id"] })
    assert_equal 3, apple_contacts.count
  end

end

On the first run, one fails and one passes. "Can't be saved without a company" fails because nothing enforces it yet. "Apple has three" passes on the empty model, because finding rows by a column comes with the table; where is not something you add to a model. Its test is still worth having: it says what "at a company" means (the company_id matches) and that Andy, at Amazon, is not counted.

One line makes the first pass:

class Contact < ApplicationRecord
  validates :company_id, presence: true
end

From a company to its contacts

Contact.where({ "company_id" => apple["id"] })

A list of every contact whose company_id is Apple's id. It's the WHERE from week 2, written in Ruby, and the SQL it writes is in log/development.log:

SELECT "contacts".* FROM "contacts" WHERE "contacts"."company_id" = 1

where always returns a list, even when it finds one row, or none.

From a contact to its company

Company.find_by({ "id" => contact["company_id"] })

One row, the company whose id the contact holds. find_by returns a single row, or nil if there isn't one.

That's the script from class, scripts/list-contacts.rb, after it saves Apple, Amazon and four contacts:

# Each contact holds its company's id. Look the company up by that id.
for contact in Contact.all
  company = Company.find_by({ "id" => contact["company_id"] })
  puts "#{contact["first_name"]} #{contact["last_name"]} (#{company["name"]})"
end

Tim Cook (Apple)
Craig Federighi (Apple)
Lisa Jackson (Apple)
Andy Jassy (Amazon)

Every line is one lookup. When the thing you want is two tables away (an activity's contact's company, in lab 3), it's two lookups, following the ids one at a time.

Why not contact.company?

Rails can hide this lookup. With belongs_to :company in the model, contact.company does the find_by for you, and has_many :contacts gives you apple.contacts. It's shorter, and in a bigger app you'd use it.

This repo's AGENTS.md tells the agent not to, and the reason is the same as for tests first: so you can see what's happening. contact.company looks like the contact contains a company. It doesn't. It holds a number, and somebody runs a WHERE with it. Once that's obvious to you, the shorthand is a convenience. Before it is, it's a mystery, and the first time it returns nil you won't know where to look.

If your agent wrote has_many or belongs_to, or a contact.company, point it at AGENTS.md and ask for the where.

The rule of thumb

Which table holds the id? The many side. One company has many contacts, so each contact holds a company_id; the company holds nothing about its contacts. One salesperson logs many activities, so each activity holds a salesperson_id. To go from the one to the many, where on that column. To go from the many to the one, find_by on id.

Code-along 3 ended with a Company model that could save, find and change rows without a line of code in app/models/company.rb. The migration gave it all of that. What it couldn't do was refuse anything: a company with no name saved as happily as Apple. This post is the second half of that code-along and the whole of code-along 4: how a rule gets written down, how it becomes a test, and what the test is for.

The rule comes first, in English

DONE.md is a file of sentences. Under each model's heading, one line per thing that must be true:

## Company
A company can't be saved without a name.
Two companies can't have the same name.

No Ruby. The question it answers is "what can't be allowed?", and the person answering it is you, because you're the one who knows what the business needs. The agent reads this file and never writes to it. That split is deliberate: if the agent wrote the rules, it would be grading its own work.

This is the definition of done. Not "the code is written", but "these sentences are true, and something proves it."

One test per sentence

The prompt from class:

My rules for Company are under Company in DONE.md. Write a test for each one, run them and show me they fail. Don't change the model yet.

The agent writes test/models/company_test.rb:

require "test_helper"

class CompanyTest < ActiveSupport::TestCase
  # One test for each sentence under Company in DONE.md, named with that sentence.

  test "a company can't be saved without a name" do
    company = Company.new
    company["city"] = "Beaverton"
    company["state"] = "OR"
    company.save

    assert_equal 0, Company.all.count
  end

  test "two companies can't have the same name" do
    company1 = Company.new
    company1["name"] = "Nike"
    company1.save

    company2 = Company.new
    company2["name"] = "Nike"
    company2.save

    assert_equal 1, Company.all.count
  end

end

Each test block is one experiment. It sets up a situation (a company with no name), does the thing (save), and states what must be true afterwards (assert_equal 0, Company.all.count: no rows). The name of the test is the sentence from DONE.md, word for word, so that when a test fails, its name tells you which rule broke.

The tests run against a separate, empty database, rebuilt for every test. Nothing you do in scripts/ or on the Data page is visible to them, and nothing they do touches your data.

Red first

bin/rails test

Failure:
CompanyTest#test_a_company_can't_be_saved_without_a_name
Expected: 0
  Actual: 1

Failure:
CompanyTest#test_two_companies_can't_have_the_same_name
Expected: 1
  Actual: 2

2 runs, 2 assertions, 2 failures, 0 errors, 0 skips

Both fail, and that is the result you wanted. The model has no rules yet, so a nameless company saved (1 row, not 0) and both Nikes saved (2, not 1). The tests are describing a problem that really exists.

This is why the prompt said "don't change the model yet." A test you have never seen fail might not be checking anything. If the agent had written the model and the tests together and shown you green, you'd have no way to tell a test that proves the rule from a test that passes no matter what. Code-along 0 made the same point with one = in place of ==: a check that can't fail is worse than no check, because it looks like one.

The name for this way of working is test-driven development, TDD: write the test, watch it fail, write the code, watch it pass. The order is the whole technique.

Check before green

Before "make them pass", open DONE.md beside the test file and do two things the agent can't do for you:

• Count. Every sentence has a test? The agent will say "done" either way. A sentence with no test is a rule your app doesn't enforce, and you'd only find out when it's broken.
• Read. Each test checks what its sentence says? The first test above sets a city and a state and leaves out the name, then expects nothing saved. If it had set a name too, it would be testing nothing.

This is the manager's seat. You don't need to write the test to tell whether it tests the rule.

Green

Make them pass.

The agent adds one line to app/models/company.rb:

class Company < ApplicationRecord
  validates :name, presence: true, uniqueness: true
end

validates states a rule on a column. presence: true refuses a blank; uniqueness: true looks in the table and refuses a duplicate. When a rule fails, save returns false instead of saving, and company.errors.full_messages says which rule: Name can't be blank.

2 runs, 2 assertions, 0 failures, 0 errors, 0 skips

Run that yourself, not just the agent. Then read the model. One line for two sentences, and you can read it against the sentences: presence is the first rule, uniqueness the second.

What the tests are for: the helpful change

Code-along 4. Imports from a spreadsheet keep failing on rows with no company name. A developer decides to help: when the name is blank, fill one in.

code-along/4-introduce-bug.rb tries to save a company with a city and no name. Before any change:

Not saved: Name can't be blank

Then the change, pasted into the model:

before_validation :fill_in_missing_name

def fill_in_missing_name
  if self["name"].blank?
    self["name"] = "Unknown company"
  end
end

before_validation runs the method every time a company is about to be checked and saved, so the blank is filled before validates looks. Run the file again:

Saved, with the name "Unknown company"

The import works now. The app runs. Nobody would notice, except:

bin/rails test

Failure:
CompanyTest#test_a_company_can't_be_saved_without_a_name
Expected: 0
  Actual: 1

2 runs, 2 assertions, 1 failures, 0 errors, 0 skips

The test named with the rule is the one that failed. It says, in the words you wrote, what the helpful change broke. The developer meant well, the code is tidy, and the rule is gone.
Without the test, the first "Unknown company" would turn up in a report three weeks later.

Take the lines back out, run the tests, green again.

Why this is the week's idea

The agent in your terminal is non-deterministic. Ask it the same thing twice and you get two different files. That is fine as long as something deterministic decides whether what it wrote is right, and that something is the tests. You write the rule; the test enforces it; the agent works until the test is green; and the next change, by you, by a teammate or by an agent, runs into the same test.

Write the definition of done before the code. Everything else in the week follows from it.

If no test fails in step 5

Then the rule was never written down as a test. Add the sentence to DONE.md and have your agent write its test. Lab 4 is a harder version of exactly this: a change that gets past a test which was written, and why.

The problem

From labs/4-regression.rb in your copy of models-and-tests:

Someone logging activities in a hurry keeps leaving the salesperson blank, and the save fails. A developer decides to help: when the salesperson is missing, use the first salesperson in the table.

Code-along 4 did this to Company with a filled-in name, and a test caught it. This lab does it to Activity, and the question is whether yours will.

1 and 2. Before you paste anything

bin/rails test

Everything passes. Now the prediction, on paper: is this a bug?

Yes. The rule in DONE.md is "An activity can't be saved without a salesperson", and the change saves exactly such an activity by inventing a salesperson for it. A note logged by nobody now belongs to whoever happens to be first in the table, and that person gets the credit, or the blame. So you expect the first test under Activity to fail.

Write that down before step 3. The lab is about comparing the prediction with what happens.

3 and 4. The helpful change

Pasted into app/models/activity.rb, under the class line:

class Activity < ApplicationRecord
  before_validation :fill_in_missing_salesperson

  def fill_in_missing_salesperson
    if self["salesperson_id"].blank?
      first_salesperson = Salesperson.all[0]
      if first_salesperson != nil
        self["salesperson_id"] = first_salesperson["id"]
      end
    end
  end

  validates :salesperson_id, presence: true
  validates :contact_id, presence: true
end

before_validation runs the method every time an activity is about to be checked and saved, so by the time validates :salesperson_id, presence: true looks, the blank has been filled. The rule is still in the file, and it's now unreachable.

bin/rails test

9 runs, 9 assertions, 0 failures, 0 errors, 0 skips

Nothing failed. The prediction was wrong, and the bug is in. To prove it's in, a script that does what the hurried person did, run with Ben and Brian in the table from lab 2:

activity = Activity.new
activity["contact_id"] = 1
activity["note"] = "left a voicemail"

if activity.save
  puts "Saved, with salesperson_id #{activity["salesperson_id"]}"
  activity.destroy
else
  puts "Not saved: #{activity.errors.full_messages.join(", ")}"
end

Saved, with salesperson_id 1

The voicemail is Ben's now (whatever his id is in your table).

5. Why the test didn't catch it

Read the test again:

test "an activity can't be saved without a salesperson" do
  activity = Activity.new
  activity["contact_id"] = 1
  activity["note"] = "met at Cupertino"
  activity.save

  assert_equal 0, Activity.all.count
end

The test database is empty when each test starts. There are no salespeople in it, so Salesperson.all[0] is nil, the if first_salesperson != nil does nothing, the salesperson_id stays blank, and the validation refuses the save. The test passes for a reason that has nothing to do with your rule: there was nobody to fill in.

That's the lab's hint, and it's a general lesson about tests. A test proves the rule only in the situation it sets up. "Can't be saved without a salesperson" was proven for an empty table. The change only misbehaves when the table has someone in it, and no test put anyone there.

So the sentence to add under Activity in DONE.md names that situation:

An activity can't be saved without a salesperson, even when there are salespeople.

Ask your agent for its test, with the change still pasted in. It should fail. Something like:

test "an activity can't be saved without a salesperson, even when there are salespeople" do
  ben = Salesperson.new
  ben["first_name"] = "Ben"
  ben["email"] = "ben@example.com"
  ben.save

  activity = Activity.new
  activity["contact_id"] = 1
  activity["note"] = "met at Cupertino"
  activity.save

  assert_equal 0, Activity.all.count
end

Failure:
ActivityTest#test_an_activity_can't_be_saved_without_a_salesperson,_even_when_there_are_salespeople
Expected: 0
  Actual: 1

4 runs, 4 assertions, 1 failures, 0 errors, 0 skips

Now it's caught. If the new test passed with the change still in, it isn't testing the rule yet: check that it saves a salesperson first.

6. Take the change out

Remove the before_validation line and the method, save, and run the tests:

10 runs, 10 assertions, 0 failures, 0 errors, 0 skips

Keep the new test. It's the one that would have caught this, and the next helpful change is usually made by an agent, in a hurry, with the best intentions.

Reflection

A test suite is only as good as the rules behind it, and a rule is only as good as the situations its test sets up. Your first test said "without a salesperson" and meant "with no salespeople anywhere", because that's the only case it built. Nobody wrote the other case down, so nothing protected it. When a change gets through, the fix is rarely in the model first. It's a sentence in DONE.md.

The problem

From labs/3-activities.rb in your copy of models-and-tests:

An activity is one thing a salesperson did with one contact: "met at Cupertino". It holds two ids, the salesperson's and the contact's.

This is the lab about the ids. An activity doesn't contain a salesperson or a contact; it holds their ids, and every question you ask of it ("whose activity is this?", "what did Ben do with Tim?") is answered by looking rows up by those ids with where or find_by. There is no has_many or belongs_to in this repo, on purpose: the rules in AGENTS.md ask your agent for the lookup, so you can see it.

1. The rules

Under Activity in DONE.md:

## Activity
An activity can't be saved without a salesperson.
An activity can't be saved without a contact.
I can find one salesperson's activities with one contact.

The third is a different kind of rule from the first two. It doesn't forbid anything; it says what you must be able to find. Both kinds belong in DONE.md.

2. Tests first, red

Your prompt, in your own words, along the lines of lab 2's: a test for each sentence, run them, show them failing, don't change the model yet. The agent should produce something like:

require "test_helper"

class ActivityTest < ActiveSupport::TestCase
  # One test for each sentence under Activity in DONE.md, named with that sentence.

  test "an activity can't be saved without a salesperson" do
    activity = Activity.new
    activity["contact_id"] = 1
    activity["note"] = "met at Cupertino"
    activity.save

    assert_equal 0, Activity.all.count
  end

  test "an activity can't be saved without a contact" do
    activity = Activity.new
    activity["salesperson_id"] = 1
    activity["note"] = "met at Cupertino"
    activity.save

    assert_equal 0, Activity.all.count
  end

  test "I can find one salesperson's activities with one contact" do
    for note in ["quick checkin over facetime", "met at Cupertino"]
      activity = Activity.new
      activity["salesperson_id"] = 1
      activity["contact_id"] = 1
      activity["note"] = note
      activity.save
    end

    activity = Activity.new
    activity["salesperson_id"] = 1
    activity["contact_id"] = 2
    activity["note"] = "met at Amazon HQ"
    activity.save

    found = Activity.where({ "salesperson_id" => 1, "contact_id" => 1 })
    assert_equal 2, found.count
  end

end

3 runs, 3 assertions, 2 failures, 0 errors, 0 skips

Two fail, one passes, and that is the right first run. The two "can't be saved" rules fail because nothing enforces them yet. The "I can find" rule passes on the empty model, because
finding rows by a column comes free with the table: where needs no code of yours. A rule that passes before you've written anything is worth a second look (is it testing something?), and here the answer is yes: it checks that two of the three activities come back, not three.

Notice the ids in the tests are made up: 1, 2. The test database starts empty for every test, so there's no salesperson 1 to look up; the test only needs an activity to hold an id. That is both convenient and a trap, and lab 4 springs it.

3. Check, then green

DONE.md beside test/models/activity_test.rb: three sentences, three tests, each named with its sentence, each checking what it says. Then "Make them pass":

class Activity < ApplicationRecord
  validates :salesperson_id, presence: true
  validates :contact_id, presence: true
end

bin/rails test

Every test in the repo green, Company and Contact included.

4. The script

scripts/activities.rb needs rows to point at, so run scripts/list-contacts.rb (from class) and scripts/salespeople.rb (lab 2) first.

# Start empty, so this can run more than once
Activity.destroy_all

ben = Salesperson.find_by({ "first_name" => "Ben", "last_name" => "Block" })
tim = Contact.find_by({ "first_name" => "Tim", "last_name" => "Cook" })
andy = Contact.find_by({ "first_name" => "Andy", "last_name" => "Jassy" })

activity = Activity.new
activity["salesperson_id"] = ben["id"]
activity["contact_id"] = tim["id"]
activity["note"] = "quick checkin over facetime"
activity.save

activity = Activity.new
activity["salesperson_id"] = ben["id"]
activity["contact_id"] = tim["id"]
activity["note"] = "met at Cupertino"
activity.save

activity = Activity.new
activity["salesperson_id"] = ben["id"]
activity["contact_id"] = andy["id"]
activity["note"] = "met at Amazon HQ"
activity.save

puts "Activities between Ben and Tim Cook:"
for activity in Activity.where({ "salesperson_id" => ben["id"], "contact_id" => tim["id"] })
  puts "- #{activity["note"]}"
end

Activities between Ben and Tim Cook:
- quick checkin over facetime
- met at Cupertino

Read how it found them. The script never stores "Ben" in an activity. It looks Ben up once, takes his id, and puts that number in each row. The question "what did Ben do with Tim?" is then one where with two ids. That is the same WHERE salesperson_id = 1 AND contact_id = 1 you'd write in SQL, and it's in log/development.log if you want to see it.

If your agent wrote activity.salesperson or ben.activities, it reached for an association. Point it at AGENTS.md.

Challenge 4 and 4a: all of Ben's activities, with the company

puts "Ben's Activities:"
for activity in Activity.where({ "salesperson_id" => ben["id"] })
  contact = Contact.find_by({ "id" => activity["contact_id"] })
  company = Company.find_by({ "id" => contact["company_id"] })
  puts "#{contact["first_name"]} #{contact["last_name"]} (#{company["name"]}) - #{activity["note"]}"
end

Ben's Activities:
Tim Cook (Apple) - quick checkin over facetime
Tim Cook (Apple) - met at Cupertino
Andy Jassy (Amazon) - met at Amazon HQ

Two lookups per line, following the ids: the activity holds a contact_id, so find the contact; the contact holds a company_id, so find the company. Each find_by on an id is one row, so the result is a single contact and a single company, not a list.

Challenge 5: a count per salesperson

for salesperson in Salesperson.all
  count = Activity.where({ "salesperson_id" => salesperson["id"] }).count
  puts "#{salesperson["first_name"]} #{salesperson["last_name"]}: #{count} activities"
end

Ben Block: 3 activities
Brian Eng: 0 activities

Brian's zero is the line to check. where with an id nobody used returns an empty list, and an empty list counts as 0, so a salesperson with no activities still gets a line. If your
version skipped Brian, it probably looped over activities instead of salespeople.

The problem

From labs/2-salespeople.rb in your copy of models-and-tests:

You write the rules in plain English; your agent writes the Ruby. Needs lab 1 first.

Four steps: the rules in DONE.md, a prompt that gets tests for them and nothing else, your check of those tests, then the code and a script. Your agent's Ruby won't match what's below line for line, and it shouldn't. What should match is the shape: every sentence has a test, each test checks its sentence, and the tests failed before the model changed.

1. The rules

Under Salesperson in DONE.md, one sentence per line. The lab suggests two questions, and each becomes a rule:

## Salesperson
A salesperson can't be saved without a first name.
Two salespeople can't have the same email.

You could write more. "A salesperson can't be saved without an email" is a reasonable third. Every sentence you write is a rule the app will enforce, so write the ones you mean. A rule you don't write down isn't a rule, and lab 4 is about what that costs.

2. The prompt

Code-along 3's prompt, with one word changed:

My rules for Salesperson are under Salesperson in DONE.md. Write a test for each one, run them and show me they fail. Don't change the model yet.

"Don't change the model yet" is the important half. Without it, an agent will happily write the tests and the code in one go and show you green. Green on the first run tells you nothing: a test you have never seen fail might not be testing anything.

The agent should write something like this in test/models/salesperson_test.rb:

require "test_helper"

class SalespersonTest < ActiveSupport::TestCase
  # One test for each sentence under Salesperson in DONE.md, named with that sentence.

  test "a salesperson can't be saved without a first name" do
    salesperson = Salesperson.new
    salesperson["last_name"] = "Block"
    salesperson["email"] = "ben@example.com"
    salesperson.save

    assert_equal 0, Salesperson.all.count
  end

  test "two salespeople can't have the same email" do
    salesperson1 = Salesperson.new
    salesperson1["first_name"] = "Ben"
    salesperson1["email"] = "ben@example.com"
    salesperson1.save

    salesperson2 = Salesperson.new
    salesperson2["first_name"] = "Brian"
    salesperson2["email"] = "ben@example.com"
    salesperson2.save

    assert_equal 1, Salesperson.all.count
  end

end

And it should run them and show you this:

Failure:
SalespersonTest#test_a_salesperson_can't_be_saved_without_a_first_name
Expected: 0
  Actual: 1

Failure:
SalespersonTest#test_two_salespeople_can't_have_the_same_email
Expected: 1
  Actual: 2

2 runs, 2 assertions, 2 failures, 0 errors, 0 skips

Read the failures. The first says a salesperson with no first name was saved: one row where there should be none. The second says both Bens were saved. Both rules are broken, which is right, because nothing enforces them yet.

3. Check its work

Before asking for the code, open DONE.md and the test file side by side.

• Count. Two sentences, two tests. A sentence with no test is a rule your app will never enforce, however sure the agent sounded when it said "done".
• Match the names. Each test is named with its sentence, so you can pair them by reading.
• Read each test. Does it do what the sentence says? The first test leaves out the first name and expects nothing saved. The second saves the same email twice and expects one row. A test that set the first name and then expected a save to fail would be checking the wrong thing, and would stay red no matter what the model did.

An agent will sometimes test a rule you didn't write (a presence check on email, say). That isn't wrong, but it isn't yours either: either add the sentence to DONE.md or ask for the test to go.

Then:

Make them pass.

4. The model

One line per rule:

class Salesperson < ApplicationRecord
  validates :first_name, presence: true
  validates :email, uniqueness: true
end

validates is how a model states a rule. presence: true refuses to save a row with that column blank. uniqueness: true looks in the table before saving and refuses if the value is already there. When a rule fails, save returns false instead of saving, and errors.full_messages says why: Email has already been taken.

Run them yourself, not just the agent:

bin/rails test

2 runs, 2 assertions, 0 failures, 0 errors, 0 skips

(If you run the whole suite, the Company and Contact tests from class run too.)

5. The script

Ask for scripts/salespeople.rb: delete every salesperson, create two, print the count and each full name.

# Start empty, so this can run more than once
Salesperson.destroy_all

ben = Salesperson.new
ben["first_name"] = "Ben"
ben["last_name"] = "Block"
ben["email"] = "ben@example.com"
ben.save

brian = Salesperson.new
brian["first_name"] = "Brian"
brian["last_name"] = "Eng"
brian["email"] = "brian@example.com"
brian.save

puts "Salespeople: #{Salesperson.all.count}"
for salesperson in Salesperson.all
  puts "#{salesperson["first_name"]} #{salesperson["last_name"]}"
end

bin/rails runner scripts/salespeople.rb

Salespeople: 2
Ben Block
Brian Eng

The destroy_all at the top is what lets you run it twice. Without it, the second run would try to save a second ben@example.com, your uniqueness rule would refuse it, and the count would stay at 2 while the script quietly skipped a row. Comment it out and run the script twice to see that happen.

Challenge: change an email after it's saved

ben["email"] = "bblock@example.com"
ben.save

Before you run it: what should the output show? The same three lines. The script never prints an email, so a changed email changes nothing you can see. That's the point of the question: the data changed, and the output didn't tell you.

To see the change, print the email, or look at the Data page in the browser, or ask the database:

puts Salesperson.find_by({ "email" => "ben@example.com" }).inspect   # nil
puts Salesperson.find_by({ "email" => "bblock@example.com" })["first_name"]   # Ben

The first is nil: nobody has the old email any more. Keep that in mind for lab 3, which looks people up. Look them up by something that doesn't change, like a name, or by the current email.

The problem

From labs/1-migrations.rb in your copy of models-and-tests:

The CRM has companies and contacts. The sales team needs two more things: the salespeople themselves, and the activities they log with contacts (a call, a meeting, a note). crm-schema.sql has all four tables in SQL; use it as your reference.

Write these two migrations yourself, no agent, the way you wrote the one for companies.

This lab is the one you type by hand, so that the next three can be about the rules rather than the typing. Everything happens in the terminal and in the files Rails makes for you.

Salesperson

From crm-schema.sql:

CREATE TABLE salespeople (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  first_name TEXT,
  last_name TEXT,
  email TEXT
);

Make the model and its migration. The model's name is singular and capitalized:

bin/rails generate model Salesperson

Rails makes two files, and names the table itself:

create    db/migrate/20261021151226_create_salespeople.rb
create    app/models/salesperson.rb

The table is salespeople, not salespersons. Rails knows how to pluralize, and it had an opinion about this one. That is the answer to step 2, and it is why the model is always named in the singular: you name the thing, Rails names the table of them.

Open the migration. Inside the create_table block, add one line per column from the SQL. Leave out id: every table gets one without asking.

class CreateSalespeople < ActiveRecord::Migration[8.1]
  def change
    create_table :salespeople do |t|
      t.string "first_name"
      t.string "last_name"
      t.string "email"

      t.timestamps
    end
  end
end

t.timestamps was already there. It adds created_at and updated_at, which Rails fills in for you on every save. The SQL file doesn't have them; that's fine.

Activity

CREATE TABLE activities (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  salesperson_id INTEGER,
  contact_id INTEGER,
  note TEXT
);

Same steps:

bin/rails generate model Activity

class CreateActivities < ActiveRecord::Migration[8.1]
  def change
    create_table :activities do |t|
      t.integer "salesperson_id"
      t.integer "contact_id"
      t.string "note"

      t.timestamps
    end
  end
end

The two id columns are integers, because they hold another table's id, which is an integer. That one column is the whole relationship between the tables: an activity knows which salesperson and which contact it belongs to by holding their ids, the same way a foreign key did in SQL. Lab 3 uses them.

Run them

bin/rails db:migrate

== 20261021151226 CreateSalespeople: migrating ================================
-- create_table(:salespeople)
== 20261021151226 CreateSalespeople: migrated (0.0010s) =======================

== 20261021151227 CreateActivities: migrating =================================
-- create_table(:activities)
== 20261021151227 CreateActivities: migrated (0.0008s) ========================

Rails runs only the migrations it hasn't run yet, in order by their number. The number is the date and time you generated the file, so yours won't match these.

Check db/schema.rb

Rails wrote it from the migrations. Never edit it by hand; it is the record of what the migrations did.

create_table "activities", force: :cascade do |t|
  t.integer "contact_id"
  t.datetime "created_at", null: false
  t.string "note"
  t.integer "salesperson_id"
  t.datetime "updated_at", null: false
end

create_table "salespeople", force: :cascade do |t|
  t.datetime "created_at", null: false
  t.string "email"
  t.string "first_name"
  t.string "last_name"
  t.datetime "updated_at", null: false
end

The columns are listed alphabetically, with the timestamps mixed in. The order doesn't matter. What matters is that every column in crm-schema.sql is there with the right type, and it is.

If something went wrong

You missed a column, and already ran the migration. Add the line to the migration file, then run bin/reset-db. It rebuilds the database from every migration in db/migrate/ and deletes every row. Your files stay as they are.

table "salespeople" already exists. There are two migrations that create it, probably because you ran generate model twice. Delete the newer one in db/migrate/ and run bin/reset-db.

The model file is empty. It should be. class Salesperson < ApplicationRecord and end is all a model needs to save, find and change rows. Lab 2 adds the rules.

code-along-complete/ in your copy of models-and-tests has every step from class,
finished. Steps 0, 1 and 4 are single files. Steps 2, 3 and 5 changed files across the app, so each is a folder that mirrors it, with a README saying which files to compare with yours.

This post is the map: what each step built, why it's there, and where the longer explanation lives. Read it beside the finished files.

0. The check: 0-replay.rb

Six games of craps, each a list of rolls and the result the rules say it must have. The game was already in the file, commented out. You wrote the check first, ran it, watched it fail (FAIL [7]: expected YOU WIN!, got not played yet), then uncommented the game and saw six PASS lines.

That order is the week's first idea. A check you have never seen fail might not be checking anything, and the three live edits proved it: break the game and the check catches it; change == to = and the check passes everything, including a broken game. The name for working this way is test-driven development.

Explained in full, with the same code: Programming Fundamentals - Lab 7 - Solution. The only differences are that the class file had the game pre-written and commented out, and the PASS line prints the rolls only.

1. Classes: 1-classes.rb

Every value has a class, and the class decides what it can do. "tacos".upcase, 7.odd?. Then a class of our own, a Dog that is a Hash (so it can hold a name) and can also speak:

class Dog < Hash
  def speak
    "woof"
  end
end

daisy = Dog.new
daisy["name"] = "Daisy"
puts daisy.speak   # woof

The step is there for one sentence at its end: a model is a class for one database table. Company.new makes one row the way Dog.new makes one dog; company["name"] reads a column the way daisy["name"] reads a key; and Company.all and Company.where are methods called on the class itself, which ask the table for rows that already exist.

The longer version: Programming Fundamentals - Classes. It was written for an older repo, so its repository link and file names are out of date; the Ruby is the same.

2. A table for companies: 2-migrations/

One migration, written by hand, and an empty model.

bin/rails generate model Company

create_table :companies do |t|
  t.string "name"
  t.string "city"
  t.string "state"
  t.string "url"

  t.timestamps
end

bin/rails db:migrate

A migration is the CREATE TABLE from week 3, as a versioned Ruby file in db/migrate/ that Rails runs in order. db/schema.rb is what Rails wrote after running it; never edit it. bin/reset-db rebuilds the database from the migrations and deletes every row, for when a migration is wrong or the database is in a state you can't explain.

The longer version: Migrations.

3, part 1. Use it: 3-companies/scripts/list-companies.rb

The first file the agent wrote. It deletes every company, saves three, finds one by name and changes its url, and prints them all:

apple = Company.new
apple["name"] = "Apple"
apple["city"] = "Cupertino"
apple.save

company = Company.find_by({ "name" => "Anthropic" })
company["url"] = "https://claude.ai"
company.save

for company in Company.all
  puts "#{company["name"]}, #{company["city"]}, #{company["url"]}"
end

app/models/company.rb was still empty when this ran. Saving, finding and changing came with the table. ActiveRecord wrote the SQL (INSERT, SELECT ... WHERE "name" = ..., UPDATE) and logged it in log/development.log.

The longer version of new, save, all, where and find_by: Models.

3, part 2 and 4. The rules, the tests, and the helpful change

DONE.md, one sentence per rule; a test for each sentence, run red before the model changes; your check that every sentence got its test; one validates line that makes them green; and then a "helpful" change to the model that the app accepts and one test refuses.

Explained in full: The definition of done, and tests.

5. Contacts: 5-contacts/

A second table that holds the first table's id, and the two lookups that make a
relationship: Contact.where({ "company_id" => apple["id"] }) from a company to its people, Company.find_by({ "id" => contact["company_id"] }) from a person to their company. No has_many, no belongs_to, on purpose.

Explained in full: Related rows, with where.

Comparing with your own copy

Your agent's tests and scripts came from your sentences, so they won't match these line for line. The things that should match: every sentence in your DONE.md has a test named with it, each test sets up the situation its sentence describes, the tests failed before the model changed, and they pass now. If you copy a file by hand, never copy a migration for a table you already have; compare it with yours instead.

The practice labs in labs/ carry on from here: two more tables by hand, then salespeople and activities from your own rules, then a change of your own to catch. Solutions:
lab 1,
lab 2,
lab 3,
lab 4.

The problem

From labs/8-weather.rb in your copy of ruby-intro:

Given the following Ruby hash that represents weather data, write a weather summary out to the screen. Something like this:

Currently it is 67 degrees and Sunny.
Forecast for the next 7 days:
- 65 degrees and Mostly Cloudy
- 70 degrees and Partly Cloudy
- 62 degrees and Sunny
- 68 degrees and Sunny
- 65 degrees and Partly Cloudy with a 70% chance of rain
- 72 degrees and Partly Cloudy
- 60 degrees and Rainy

Note: only display the chance of rain if above 50%.
Note: do not display the chance of rain if conditions are already rainy.

Run it from the top folder of the repo:

bin/rails runner labs/8-weather.rb

This one uses everything: a hash, an array inside it, a loop over the array, and a conditional inside the loop.

Steps

1. Look at the weather_data hash.
2. Find the current conditions and display the first line.
3. Find the array of forecast data.
4. Loop through it, displaying one line per day.
5. Inside the loop, decide whether that day mentions the chance of rain.

1. Look at the hash, and notice the keys

weather_data = {
  current: {
    temperature: 67,
    conditions: "Sunny"
  },
  forecast: [
    { temperature: 65, conditions: "Mostly Cloudy", precipitation: 0.4 },
    ...
    { temperature: 60, conditions: "Rainy", precipitation: 0.9 }
  ]
}

The top level has two keys, current and forecast. current is a hash. forecast is an array of hashes, one per day: a table, with a row for each day.

The keys are written differently from the hashes we've built so far. current: { ... } is short for :current => { ... }. The key is a symbol, a word that starts with a colon, not a string. The hashes code-along mentioned this at the end: two ways to write a hash. It matters here because a symbol key and a string key are different keys:

puts weather_data["current"]   # nothing: there is no "current" key
puts weather_data[:current]    # {temperature: 67, conditions: "Sunny"}

If you get nil, or an error like undefined method '[]' for nil, this is the first thing to check. Use the key the way the hash was written.

2. The current conditions

Start with the sample line exactly as written, then swap the parts that should change:

puts "Currently it is 67 degrees and Sunny."

current = weather_data[:current]
puts "Currently it is #{current[:temperature]} degrees and #{current[:conditions]}."

3 and 4. Loop through the forecast

We could pull out each day by its index, weather_data[:forecast][0], then [1], and so on. But that's seven nearly identical lines, and it breaks the day the forecast has eight days. A loop does it once, for however many days there are:

puts "Forecast for the next #{weather_data[:forecast].size} days:"
for day in weather_data[:forecast]
  puts "- #{day[:temperature]} degrees and #{day[:conditions]}"
end

Each time around, day is one hash from the array. .size counts the days, so the heading is right even if the forecast changes.

5. The chance of rain

Two notes in the problem, two conditions, and both have to be true:

• the chance of rain is above 50%: day[:precipitation] > 0.5
• it isn't already rainy: day[:conditions] != "Rainy"

&& means both. != means "is not equal to."

  if day[:precipitation] > 0.5 && day[:conditions] != "Rainy"
    chance_of_rain = (day[:precipitation] * 100).round
    puts "- #{day[:temperature]} degrees and #{day[:conditions]} with a #{chance_of_rain}% chance of rain"
  else
    puts "- #{day[:temperature]} degrees and #{day[:conditions]}"
  end

precipitation is stored as a fraction, 0.7, so we multiply by 100 for a percentage. 0.7 * 100 is 70.0, a Float, which would print as "70.0%"; .round makes it a whole number.

Check the output against the notes. Day 5 (0.7, Partly Cloudy) mentions rain. Day 7 (0.9) has a higher chance, but it's already Rainy, so it doesn't. Day 1 (0.4) is under 50%.

Final code

# 1. inspect the weather_data hash
# puts weather_data

# 2. the current conditions; the keys are symbols, so :current, not "current"
current = weather_data[:current]
puts "Currently it is #{current[:temperature]} degrees and #{current[:conditions]}."

# 3. the forecast is an array of hashes, one per day
puts "Forecast for the next #{weather_data[:forecast].size} days:"

# 4. loop through it, one line per day
for day in weather_data[:forecast]

  # 5. mention the chance of rain only if it's above 50% and it isn't already rainy
  if day[:precipitation] > 0.5 && day[:conditions] != "Rainy"
    chance_of_rain = (day[:precipitation] * 100).round
    puts "- #{day[:temperature]} degrees and #{day[:conditions]} with a #{chance_of_rain}% chance of rain"
  else
    puts "- #{day[:temperature]} degrees and #{day[:conditions]}"
  end
end

Output:

Currently it is 67 degrees and Sunny.
Forecast for the next 7 days:
- 65 degrees and Mostly Cloudy
- 70 degrees and Partly Cloudy
- 62 degrees and Sunny
- 68 degrees and Sunny
- 65 degrees and Partly Cloudy with a 70% chance of rain
- 72 degrees and Partly Cloudy
- 60 degrees and Rainy

Challenge

Add a line under the forecast that says which day will be the warmest, something like "The warmest day will be day 6, at 72 degrees." You'll need a variable that remembers the highest temperature so far, set before the loop and updated inside it.