workspace-course-topics

Assignment: Create Intro Notebook

Due: Before next class

Prerequisites:

Ballpark Paper Selection — you’ve chosen a paper and have a GitHub account
The summary notebook {BALLPARK}_summary.ipynb exists in your paper folder (create it by copying the original notebook; if the original might be a Jupyter slideshow, run the convert-slideshow-to-notebook prompt on the copy first, which will do nothing if it is not a slideshow — see the Class 05 assignment for these initial steps)

Throughout this document, {BALLPARK} stands for your paper’s folder name (e.g. OptimumDebt, HKMOHousingChannelMP). Always replace it with your actual folder name.

Objective

Create an intro notebook that identifies the paper, its authors, and you as the student contributor.

The intro notebook is the single source of truth (SST) for attribution metadata — all “Updated by” information lives here and nowhere else. It will be the first item in your MyST TOC.

Ask Cursor Throughout

Use Cursor as your advisor for Git commands. If you’re unsure about any step:

“I’m trying to [describe what you want to do]. What Git command should I use?”

For example:

“I want to create a new branch for my changes”
“I pushed to the wrong place, how do I fix it?”
“What does this error message mean?”

Part A: Fork and set up your working environment

Already have a fork and PR branch? If you already forked the ballpark repo and have an open PR from earlier work, skip to Part B. Just make sure you’re on your existing PR branch:
cd ~/github/<your-username>/ballpark
git checkout <your-PR-branch>
git pull origin <your-PR-branch>
If you don’t remember your branch name, run git branch to see the list.

1. Fork the ballpark repository

If you haven’t already forked ballpark:

Go to https://github.com/econ-ark/ballpark
Click Fork (top right)
Select your GitHub account as the destination
You now have your own copy at https://github.com/YOUR-USERNAME/ballpark

2. Clone your fork and run setup

git clone https://github.com/YOUR-USERNAME/ballpark.git
cd ballpark
bash scripts/setup_env.sh

3. Set up remotes

# Check current remotes
git remote -v

# If 'origin' points to your fork, add upstream:
git remote add upstream https://github.com/econ-ark/ballpark.git

# If 'origin' points to econ-ark/ballpark, rename and add your fork:
git remote rename origin upstream
git remote add origin https://github.com/YOUR-USERNAME/ballpark.git

# Verify — you should see both 'origin' (your fork) and 'upstream' (econ-ark)
git remote -v

4. Create a branch for your work

# Make sure you're up to date
git checkout master
git pull upstream master

# Create your working branch
git checkout -b ballpark-YOURNAME

Replace YOURNAME with your name (no spaces, e.g., ballpark-smith).

You will use this same branch for all four notebook assignments and the final PR.

Part B: Create the intro notebook

5. Navigate to your paper folder

cd models/We-Would-Like-In-Econ-ARK/{BALLPARK}/

6. Create the notebook file

Create {BALLPARK}_intro.ipynb in the paper folder. For example, if the summary notebook is HKMOHousingChannelMP_summary.ipynb, create HKMOHousingChannelMP_intro.ipynb.

You can create this in Cursor: File > New File, save as {BALLPARK}_intro.ipynb.

7. Add content (markdown cells)

The intro notebook is the single source of truth for attribution. Do not add “Updated by” lines to the summary or any other notebook — all such information lives here. Add markdown cells with:

Paper: [Full title], [authors], [year], [venue]. Include the DOI link if known.
Original ballpark authors: [Name(s)] — [date(s) created]
- Note: {BALLPARK}_summary.ipynb is a copy you made — it has no git history of its own. Look at the original notebook (the one you copied from, which has a different filename). Inspect it for author information, run git log --follow on the original file, or check the folder’s commit history on GitHub.
Updated by: [Your name] — [today’s date]

No code cells are needed. No bibliography required for this notebook.

Part C: Commit

# Verify you're on your branch
git branch --show-current

# Stage the intro notebook
git add {BALLPARK}_intro.ipynb
git commit -m "Create intro notebook for [Your Paper] — [Your Name]"

Deliverable

{BALLPARK}_intro.ipynb created and committed, containing all attribution metadata

What to check: Open the notebook and verify it has the paper’s full title and authors, the original ballpark contributor’s name and date, and your name as “Updated by.”

Troubleshooting

“Permission denied” or authentication errors:

Make sure your GitHub credentials are configured. Ask Cursor: “How do I set up Git authentication for GitHub?”

“Can’t find the notebook”:

Make sure Cursor is open at the ballpark root (not a subdirectory)
Navigate through: models → We-Would-Like-In-Econ-ARK → [your paper folder]

Branch or remote confusion:

Run git remote -v and git branch --show-current to see where you are
Ask Cursor to help sort out any remote/branch issues

If You Get Stuck

Ask Cursor AI. If the “auto” model is inadequate, try Claude Opus 4.6 or ChatGPT 5.3.

Next Step

Create Prior-Literature Notebook