Lab: First Safe Pull Request

Goal: create a small, understandable, tested pull request without editing main directly.

Prerequisites: Git installed, GitHub access working, and the Code Contributor Track started.

Execution context: run Git commands on your local computer. They work in Windows PowerShell, macOS zsh, and Linux Bash. Do not run them on Euler unless the project intentionally lives there.

1. Clone The Training Repository#

Use the route matching the authentication method you configured. Do not try all routes or put a token in a URL.

VS Code OAuth route#

1. Open the Command Palette and select Git: Clone.
2. Enter https://github.com/IDEALLab/FirstSteps.git.
3. Complete the browser sign-in if requested, choose a local parent folder, and open the cloned repository.

GitHub CLI route#

gh auth status
gh repo clone IDEALLab/FirstSteps
cd FirstSteps

GitHub SSH route#

Use this only after GitHub's SSH authentication test succeeds:

git clone git@github.com:IDEALLab/FirstSteps.git
cd FirstSteps

For every route, run in the cloned repository:

git status --short --branch
git remote get-url origin

Expected result: Git reports the repository's default branch and a clean working tree. If authentication fails, use the GitHub authentication section of the Git guide; do not put a token in the clone URL.

2. Inspect Before Editing#

git status --short --branch
git log --oneline -5

Read the repository README.md, contribution instructions, tests, and agent instructions before changing files.

Use this passport page as the canonical Git/authentication procedure. If the training README links an old handbook branch or shows a non-Conventional commit message, do not copy that stale instruction; report it as a documentation defect.

Confirm that the repository declares how to install every required check. If Ruff, mypy, or pre-commit is requested but no reproducible development setup is declared, stop and open a documentation issue; do not install guessed global packages merely to make the exercise continue.

Optional agent task:

Goal: explain the training repository and current task without editing.
Context: inspect README, contribution/agent instructions, source, and tests.
Constraints: do not modify files or run network commands.
Verification: list inspected files and the command that reproduces the issue.
Output: explain the expected behavior and smallest safe next step.

3. Create A Branch#

Windows laptop - PowerShell#

$EthUser = Read-Host "ETH username"
if ($EthUser -notmatch '^[A-Za-z0-9._-]+$') { throw "Invalid ETH username" }
git switch -c "onboarding/$EthUser-first-pr"

macOS or Linux laptop - zsh/Bash#

read -r -p "ETH username: " eth_user
case "$eth_user" in
  ''|*[!A-Za-z0-9._-]*) printf 'STOP: invalid ETH username\n' >&2 ;;
  *) git switch -c "onboarding/${eth_user}-first-pr" ;;
esac

Expected result: git status --short --branch names the new branch.

4. Reproduce, Test, And Make A Small Change#

Run the repository's documented reproduction/test command. Add or adjust one test when appropriate, make the smallest fix, then inspect:

git status --short
git diff --check
git diff

Do not stage until you can explain every line.

5. Stage And Commit Intentionally#

For the current FirstSteps exercise, stage only the exercise file. If a future task legitimately changes more files, add their exact reviewed paths instead of using git add -A:

git add -- first_steps/execute_me.py
git diff --cached
git commit -m "chore(firststeps): format exercise code"

The shown commit message matches a formatting-only diff. If your reviewed diff changes behavior, write an accurate fix(firststeps): ... summary instead.

A Conventional Commit uses type(scope): summary. The scope identifies the affected component; it is not a version number. Common types include fix, feat, docs, test, refactor, and chore.

6. Push And Open A Draft PR#

Windows laptop - PowerShell#

$Branch = git branch --show-current
if ([string]::IsNullOrWhiteSpace($Branch) -or $Branch -in @('main', 'master')) {
    throw "STOP: create the onboarding branch before pushing"
}
git push -u origin HEAD

macOS or Linux laptop - zsh/Bash#

branch="$(git branch --show-current)"
case "$branch" in
  ''|main|master) printf 'STOP: create the onboarding branch before pushing.\n' >&2 ;;
  *) git push -u origin HEAD ;;
esac

Open a draft pull request on GitHub. Include:

Purpose:
Changes:
Interfaces or users affected:
Verification actually run:
Risks or limitations:
AI assistance used:

An interface is a boundary another person or component relies on, such as a function signature, file format, command-line option, configuration key, API, or documented procedure. Write None when the change affects no interface; do not invent an impact. If it does, request review from the person responsible for that interface or its downstream use.

Do not merge the FirstSteps training pull request. Request the named reviewer and leave the PR available as evidence.

Verification#

• git status --short is clean after the commit.
• The branch is not main.
• The PR diff contains only intended source/test/documentation changes.
• The PR reports exact tests actually run.
• The PR identifies affected interfaces/users and an appropriate reviewer.
• No token, .env, dataset, checkpoint, cache, or generated result appears.

Common Failures And Safe Recovery#

• Wrong files staged: use git restore --staged <path>; this unstages but keeps the local edit.
• Agent changed too much: inspect git diff, then restore only understood unwanted paths. Do not use git reset --hard.
• Push rejected: fetch and inspect remote changes before merging/rebasing.
• Secret committed: revoke it immediately and report it before attempting history cleanup.

Understand Before Accepting AI Output#

• I reproduced the behavior myself.
• I can explain every changed line.
• I know what the test proves.
• I checked the staged diff before committing.
• The PR does not claim checks I did not run.

Evidence#

Submit the PR URL, commit message, verification commands, and a short explanation of one AI suggestion you accepted or rejected and why.

Ask For Help When#

The repository instructions conflict, a secret enters history, the default branch contains unexpected changes, or recovery would rewrite shared history.