Learning Room Automation Guide

Welcome! The Learning Room uses intelligent automation to provide instant feedback while preserving the value of human peer review. This guide explains how the automation works and how to interpret its feedback.

What Gets Automated

1. PR Validation Bot

When you open a pull request, the bot automatically:

The bot runs on every PR update, so you'll see new feedback as you make changes.

2. Skills Progression Engine

As you complete challenges:

3. Student Pairing & Grouping

To ensure everyone gets reviewed:

Understanding Bot Feedback

Validation Report Structure

When the bot comments on your PR, it provides:

Required Checks /

These MUST pass before merge:

Suggestions

Optional improvements that enhance quality:

Accessibility Analysis

Detailed checks organized by severity:

Each accessibility issue includes:

Learning Resources

Links to relevant documentation based on your PR content

Common Validation Issues & Fixes

"No issue reference found"

What this means: Your PR description doesn't link to an issue.

Why it matters: Linking PRs to issues provides context and helps track work.

How to fix: Add one of these patterns to your PR description:

Closes #42
Fixes #42
Resolves #42

Screen reader tip: Use the "Reference in new issue" button in the GitHub UI, or type # followed by the issue number to get autocomplete.

"Heading hierarchy violation"

What this means: Your document skips heading levels (e.g., H1 → H3 without H2).

Why it matters: Screen readers use headings for navigation. Skipping levels creates confusion.

Example problem:

# Main Title (H1)
### Sub-section (H3) ← SKIP! Missing H2

How to fix:

# Main Title (H1)
## Section (H2)
### Sub-section (H3) ← Proper hierarchy

Resources:

"Generic link text detected"

What this means: Your link text is "click here", "here", "read more", etc.

Why it matters: Screen reader users often navigate by links. Generic text doesn't describe the destination.

Example problem:

For more information, [click here](https://example.com).

How to fix:

Read the [GitHub accessibility documentation](https://example.com).

Key principle: Link text should make sense out of context.

"Missing alt text"

What this means: An image has no alt text or empty alt text.

Why it matters: Screen readers announce alt text so blind users understand images.

Example problem:

![](screenshot.png)

How to fix:

![Screenshot showing the GitHub Issues page with three open issues labeled "bug"](screenshot.png)

Alt text guidelines:

Resources:

"Broken relative link"

What this means: A link points to a file that doesn't exist.

Example problem:

See [installation guide](docs/install.md)  ← File doesn't exist

How to fix:

  1. Check the file path is correct
  2. Ensure the file exists in the repository
  3. Use correct relative paths from your file's location

Path examples:

"[TODO] markers remaining"

What this means: Your file contains [TODO] placeholders.

Why it matters: Incomplete work shouldn't be merged.

How to fix: Complete all TODO items or remove the markers if work is done.

Getting Help

Ask the Bot

You can interact with the bot by commenting on your PR:

Request Human Review

The bot is not a substitute for peer review! Always request review from:

  1. Your peer reviewer (assigned automatically)
  2. Study group members (if in a group)
  3. Facilitators (for complex questions)

Click "Reviewers" in the PR sidebar and select someone.

Ask in Your PR

If you're stuck:

  1. Comment on your PR with your specific question
  2. Tag your peer reviewer or study group
  3. Facilitators monitor all PRs and will help

Skills Progression System

Skill Levels

Beginner (0+ merged PRs)

Intermediate (1+ merged PRs)

Advanced (3+ merged PRs)

Expert (5+ merged PRs)

How Progression Works

  1. Complete a challenge by opening a PR that closes an issue
  2. Get peer review and make requested changes
  3. Merge your PR when approved
  4. Receive your badge and see progress update
  5. New challenges unlock based on your level

Achievement Badges

Milestones

Special celebrations at: 1, 5, 10, 25, 50, and 100 merged PRs!

Peer Review & Grouping

Automatic Reviewer Assignment

When you open a PR:

  1. Bot assigns a peer reviewer automatically
  2. They receive a notification
  3. You both get guidance on the review process

Study Groups

Facilitators may create study groups that:

If assigned to a group, you'll get an issue thread for communication.

Review Guidelines

When reviewing others:

When receiving reviews:

Troubleshooting

"Bot comment is out of date"

The bot updates its comment when you push changes. If it seems wrong:

  1. Check if your latest commit is the one being validated
  2. Wait a few seconds for GitHub Actions to complete
  3. Look at the "Checks" tab for real-time status

"I fixed it but bot still reports error"

Make sure you:

  1. Committed your changes (git add, git commit)
  2. Pushed to GitHub (git push)
  3. Waited for checks to complete (~30 seconds)

"Bot assigned wrong reviewer"

The assignment is automatic but not perfect. You can:

  1. Request additional reviewers manually
  2. Ask in your study group
  3. Tag someone specific if they have relevant expertise

"I disagree with bot's feedback"

The bot isn't always right! If you believe feedback is incorrect:

  1. Comment explaining your reasoning
  2. Request human review for a second opinion
  3. Facilitators can override bot checks

"Bot is commenting too much"

Each PR gets ONE comment that updates. If you're seeing multiple:

  1. This might be a bug - notify facilitators
  2. Check if comments are from different bots/workflows

Philosophy: Automation + Human Review

Why Both?

Automation provides:

Human review provides:

The Best of Both

By combining automation with peer review:

This mirrors professional development where CI/CD handles checks and humans provide code review.

Additional Resources

Feedback on Automation

Found a bug? Have suggestions for improving the automation?

Open an issue with label automation-feedback and let us know!

Setting Up Automation for Your Workshop

The automation features described above (PR validation, skills progression, student pairing) require GitHub Actions workflows that facilitators must configure for their own deployment. These workflows are not included in this repository because each workshop instance may have different requirements.

What facilitators need to create:

  1. PR validation workflow - A GitHub Actions workflow (.github/workflows/pr-validation.yml) triggered on pull_request events that runs the checks described in the "PR Validation Bot" section above
  2. Skills tracker - A workflow or bot that monitors merged PRs and updates contributor progress
  3. Reviewer assignment - A workflow that auto-assigns peer reviewers when PRs are opened

Resources for building these:

This system was designed with accessibility and inclusive learning at its core. Every student deserves instant, helpful feedback and supportive peer connections.