|
1871 | 1871 | "url": "learning-room/docs/welcome.html", |
1872 | 1872 | "body": "Welcome to Open Source Contribution This guide is for people who are new to contributing to open source software. It explains what contribution means, who it is for, and how to get started. Workshop practice file: This Learning Room copy intentionally includes [TODO] sections for students to complete during the contribution challenges. If you are not working on the assigned challenge, leave the placeholders in place. What Is Open Source? Open source software is software whose source code is publicly available. Anyone can read it, use it, and - in most cases - contribute to it. Contributions can include: Fixing bugs in the software Writing or improving documentation Filing bug reports Reviewing other people's changes Translating content into other languages Improving accessibility You do not need to be a professional developer to contribute. Documentation, accessibility improvements, and bug reports are among the most valuable contributions an open source project can receive. Who Can Contribute? [TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. Emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.] What Makes a Good First Contribution? A good first contribution is: Specific - it addresses one problem clearly Scoped - it does not try to fix everything at once Described - the PR or issue explains what changed and why Tested - for documentation, this means reading it aloud with your screen reader before submitting Finding Something to Work On Most open source projects label issues that are suitable for new contributors. Look for: good first issue first-timers-only help wanted beginner [TODO: Add two or three sentences about how to read an issue to decide if it is right for you. What questions should you ask yourself? Is the description clear enough? Is anyone else already working on it?] Getting Help It is always acceptable to ask a question on an issue or pull request. Good questions: Are specific: "I'm trying to fix the broken link on line 24 of setup-guide.md. The link currently points to /docs/old-setup. Where should it point?" Show what you tried: "I searched the repository for the correct URL but couldn't find it" Are polite: assume good intent from maintainers, even if they are slow to respond After Your Contribution Is Merged When your pull request is merged: Your name appears in the project's commit history permanently The issue you fixed is closed You are officially listed as a contributor to this project [TODO: Add a sentence or two about what this means for someone's GitHub profile and open source portfolio.] Last reviewed: [DATE] Authoritative Sources Use these official references when you need the current source of truth for facts in this chapter. GitHub Docs, home GitHub Changelog Section-Level Source Map Use this map to verify facts for each major section in this file. What Is Open Source?: GitHub Docs, home , GitHub Changelog Who Can Contribute?: GitHub Docs, home , GitHub Changelog What Makes a Good First Contribution?: GitHub Docs, home , GitHub Changelog Finding Something to Work On: GitHub Docs, home , GitHub Changelog Getting Help: GitHub Docs, home , GitHub Changelog After Your Contribution Is Merged: GitHub Docs, home , GitHub Changelog , About Git , GitHub flow , About pull requests" |
1873 | 1873 | }, |
1874 | | - { |
1875 | | - "id": "learning-room/docs/code-review-sample.html", |
1876 | | - "title": "Review Me: Sample Markdown for Code Review Practice", |
1877 | | - "url": "learning-room/docs/code-review-sample.html", |
1878 | | - "body": "Review Me: Sample Markdown for Code Review Practice Welcome to the code review challenge! This file is intentionally written with a few issues for you to find and improve. Your task is to review this markdown, suggest improvements, and submit a pull request with your changes. What to look for Typos or unclear language Missing or incorrect headings Inconsistent formatting Missing alt text for images Any accessibility or clarity issues Example Section this is a section with no heading capitalization Here is a list: item one *item two (missing space) item three Here is a link: example website Next Steps Fork or branch this repository. Edit this file to fix any issues you find. Commit your changes with a clear message. Open a pull request for review. Thank you for participating in the review! Authoritative Sources Use these official references when you need the current source of truth for Markdown review, headings, links, and accessibility checks. GitHub Docs, home GitHub Flavored Markdown spec GitHub Pages docs Section-Level Source Map What to look for: GitHub Docs, home , GitHub Flavored Markdown spec Example Section: GitHub Docs, home , GitHub Flavored Markdown spec Next Steps: GitHub Docs, home , GitHub Pages docs" |
1879 | | - }, |
1880 | 1874 | { |
1881 | 1875 | "id": "learning-room/docs/course-roadmap.html", |
1882 | 1876 | "title": "Course Roadmap", |
|
1901 | 1895 | "url": "learning-room/docs/setup-guide.html", |
1902 | 1896 | "body": "Setup Guide Getting Ready to Contribute with a Screen Reader This guide walks you through everything you need to set up before your first GitHub contribution. Complete all steps before the workshop begins. Workshop practice file: This Learning Room copy intentionally contains a few small issues for students to find and fix during the workshop. Follow your assigned challenge issue before changing any [TODO] marker or broken sample link. Step 1 - Create a GitHub Account If you don't already have a GitHub account, create one at github.com/join . Account name tips: Choose something you're comfortable sharing publicly - your GitHub username will appear in commit history Avoid special characters other than hyphens Your username cannot be changed easily later Step 2 - Configure Accessibility Settings GitHub has several accessibility settings that make navigation significantly easier with a screen reader. These settings are per-account and sync across devices. Navigate to github.com/settings/accessibility Under "Motion", disable any animated effects if motion causes you difficulty Under "Tab size", set to your preferred number of spaces Confirm the page reads "Accessibility settings saved" before leaving Step 3 - GitHub Interface (No Action Needed) GitHub's improved Issues and Pull Request experiences have been broadly rolled out and are likely already active for your account. However, some features may still appear as opt-in toggles in Feature Preview for some users. You should automatically have: Modern Issues experience with proper heading hierarchy and better screen reader navigation Improved Pull Request Files Changed view with accessible diff navigation Better keyboard accessibility throughout GitHub To verify: Activate the User Menu button (top right) → "Feature preview" → scan the list. Each toggle announces "Pressed" when enabled. If neither "New Issues Experience" nor "New Files Changed Experience" appears in the list, both have graduated to the standard interface and are active automatically. If something doesn't match the workshop materials, verify your Feature Preview settings as above, then try clearing your browser cache and reloading the page. Step 4 - Disable Hovercards GitHub's hovercards appear when your mouse hovers over a username or repository. For keyboard users, these can interfere with focus and create unexpected announcements. Navigate to your account settings: github.com/settings Scroll to the "Hovercards" section Uncheck "Show user hovercards" Save the changes Step 5 - Configure Your Screen Reader for GitHub NVDA Set the NVDA user interface language to match your system language (NVDA Menu → Preferences → Settings → General) In Browse Mode settings: set "Maximum length of text" to 10000 Recommended browser: Google Chrome with the NVDA Google Chrome extension installed JAWS Confirm JAWS is set to use the "Standard" verbosity level (JAWS Key + V → select Standard) When on GitHub, use Virtual PC Cursor (reading mode) for general navigation Switch to Forms Mode (Enter on a field) when filling out issue or comment forms VoiceOver (macOS) Open VoiceOver Utility (Command+F5 to start VoiceOver → VO+F8 for utility) Verbosity → Punctuation: set to "Some" or "All" for reading code blocks Recommended browser: Safari (best VoiceOver compatibility) or Google Chrome Step 6 - Fork the Workshop Repository To make your own contributions, you need your own copy of the repository. Navigate to the workshop repository: [TODO: Add link to workshop repository here] Find the "Fork" button in the top-right area of the page (navigate by button: B) Choose your GitHub account as the destination GitHub creates a fork: a copy of the repository that belongs to you Your fork is at: github.com/[your-username]/[repository-name] Step 7 - Verify Your Setup Before the workshop begins, confirm that you can: Navigate to github.com and read the page headings with your screen reader Find and read an issue in the Issues tab of the workshop repository Read a pull request description Access your account settings If any of these steps are difficult, bring your question to the workshop. There will be dedicated setup time at the start of Day 1. Getting Help Before the Workshop If you run into setup issues before the workshop: Open an issue in the workshop repository using the "Feature or Improvement Request" template Ask your question in the issue - be specific about what step you are on and what happens when you try it Facilitator note: Links marked [TODO] and the sample broken link in this document are intentional practice targets for student issues and pull requests. Authoritative Sources Use these official references when you need the current source of truth for facts in this chapter. GitHub Docs, home GitHub Changelog Section-Level Source Map Use this map to veri" |
1903 | 1897 | }, |
| 1898 | + { |
| 1899 | + "id": "learning-room/docs/code-review-sample.html", |
| 1900 | + "title": "Review Me: Sample Markdown for Code Review Practice", |
| 1901 | + "url": "learning-room/docs/code-review-sample.html", |
| 1902 | + "body": "Review Me: Sample Markdown for Code Review Practice Welcome to the code review challenge! This file is intentionally written with a few issues for you to find and improve. Your task is to review this markdown, suggest improvements, and submit a pull request with your changes. What to look for Typos or unclear language Missing or incorrect headings Inconsistent formatting Missing alt text for images Any accessibility or clarity issues Example Section: Getting Started with Version Control this is a section with no heading capitalization Version control is a tool that helps teams keep track of changes to files over time. It allows multiple people to work on the same project without overwriting each other's work. When you make changes, version control records what was changed, who changed it, and when the change was made. This creates a complete history of the project that you can refer back to at any time. Understanding version control is essential for working in teams and contributing to open source projects. Many professionals use version control systems like Git every single day as part of their normal workflow. By learning version control early, you prepare yourself for collaborative development work that matches what you will encounter in real jobs. Here is a list: item one *item two (missing space) item three The most common workflow with version control involves several key steps. First, you make changes to your code or documentation. Next, you review those changes to make sure they are correct. Then you package them together in a commit with a clear message explaining what you changed and why. Finally, you share that commit with your team by pushing it to a shared repository. This cycle repeats many times throughout a project's life. Here is a link: example website Why This Matters Learning to work effectively with version control is one of the most valuable skills in software development. Whether you are fixing bugs, adding new features, or documenting your work, version control helps you organize your efforts and communicate with your team. It also provides a safety net if you ever need to undo changes or investigate how a bug was introduced into the codebase. Next Steps Fork or branch this repository. Edit this file to fix any issues you find. Commit your changes with a clear message. Open a pull request for review. Thank you for participating in the review! Authoritative Sources Use these official references when you need the current source of truth for Markdown review, headings, links, and accessibility checks. GitHub Docs, home GitHub Flavored Markdown spec GitHub Pages docs Section-Level Source Map What to look for: GitHub Docs, home , GitHub Flavored Markdown spec Example Section: GitHub Docs, home , GitHub Flavored Markdown spec Next Steps: GitHub Docs, home , GitHub Pages docs" |
| 1903 | + }, |
1904 | 1904 | { |
1905 | 1905 | "id": "learning-room/index.html", |
1906 | 1906 | "title": "Welcome to the Learning Room", |
|
0 commit comments