-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathCONTRIBUTING.html
More file actions
652 lines (624 loc) · 44.6 KB
/
Copy pathCONTRIBUTING.html
File metadata and controls
652 lines (624 loc) · 44.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="GIT Going with GitHub - A two-day accessible open source workshop by Community Access">
<title>Contributing to This Workshop Repository - GIT Going with GitHub</title>
<link rel="stylesheet" href="./styles/github-markdown.css">
<link rel="stylesheet" href="./styles/highlight.css">
<link rel="stylesheet" href="./styles/custom.css">
<style>
.markdown-body {
box-sizing: border-box;
min-width: 0;
max-width: 980px;
margin: 0;
padding: 45px;
}
.page-layout {
max-width: 1320px;
margin: 0 auto;
padding: 1rem 1rem 2rem;
display: grid;
grid-template-columns: minmax(240px, 300px) minmax(0, 1fr);
gap: 1.25rem;
align-items: start;
}
@media (max-width: 767px) {
.page-layout {
grid-template-columns: 1fr;
padding: 0.5rem 0.5rem 1rem;
}
.markdown-body {
padding: 15px;
}
}
</style>
</head>
<body>
<a class="skip-link" href="#main-content">Skip to main content</a>
<header class="site-header" role="banner">
<div class="site-header-inner">
<nav aria-label="Breadcrumb" class="breadcrumb">
<a href="./index.html">Home</a> <span aria-hidden="true">›</span> <span aria-current="page">Contributing to This Workshop Repository</span>
</nav>
<div class="header-actions">
<a href="https://github.com/Community-Access/git-going-with-github/wiki" class="wiki-link" target="_blank" rel="noopener noreferrer">
<svg aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
<path d="M1.75 1h8.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 10.25 10H7.06l-2.573 2.573A1.458 1.458 0 0 1 2 11.543V10h-.25A1.75 1.75 0 0 1 0 8.25v-5.5C0 1.784.784 1 1.75 1ZM1.5 2.75v5.5c0 .138.112.25.25.25h1a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h3.5a.25.25 0 0 0 .25-.25v-5.5a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm13 2a.25.25 0 0 0-.25-.25h-.5a.75.75 0 0 1 0-1.5h.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 14.25 12H14v1.543a1.457 1.457 0 0 1-2.487 1.03L9.22 12.28a.749.749 0 1 1 1.06-1.06l2.22 2.22v-2.19a.75.75 0 0 1 .75-.75h.25a.25.25 0 0 0 .25-.25v-5.5Z"/>
</svg>
Wiki
</a>
<form role="search" class="search-form" action="./search.html" method="get">
<label for="site-search" class="search-label">Search docs</label>
<input
type="search"
id="site-search"
class="search-input"
name="q"
placeholder="Search docs…"
autocomplete="off"
aria-label="Search documentation"
>
<button type="submit" class="search-button" aria-label="Submit search">
<svg aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
<path d="M10.68 11.74a6 6 0 0 1-7.922-8.982 6 6 0 0 1 8.982 7.922l3.04 3.04a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215ZM11.5 7a4.499 4.499 0 1 0-8.997 0A4.499 4.499 0 0 0 11.5 7Z"/>
</svg>
</button>
</form>
</div>
</div>
</header>
<div class="page-layout">
<aside class="guided-sidebar" aria-label="Guided reference">
<h2 class="guided-title">Guided Reference</h2>
<p class="guided-intro">Follow the learning order, then jump into challenge issue views, appendices, and support resources.</p>
<section class="guided-resume" aria-label="Resume learning">
<a id="resume-link" class="guided-resume-link" href="./index.html" hidden>Resume where you left off</a>
</section>
<nav class="guided-nav" aria-label="Workshop navigation">
<section class="guided-section">
<h3>Start Here</h3>
<ul>
<li><a href="./index.html">Workshop Home</a></li>
<li><a href="./docs/course-guide.html">Course Guide</a></li>
<li><a href="./docs/get-going.html">Get Going with GitHub</a></li>
<li><a href="./docs/CHALLENGES.html">Challenge Hub</a></li>
</ul>
</section>
<section class="guided-section">
<h3>Learning Order</h3>
<details>
<summary>Day 1 chapters</summary>
<ul>
<li><a href="./docs/00-pre-workshop-setup.html">Pre-Workshop Setup - GIT Going with GitHub</a></li>
<li><a href="./docs/01-choose-your-tools.html">Choose Your Adventure: A Tool Tour</a></li>
<li><a href="./docs/02-understanding-github.html">Understanding GitHub's Web Structure</a></li>
<li><a href="./docs/03-navigating-repositories.html">Navigating Repositories</a></li>
<li><a href="./docs/04-the-learning-room.html">The Learning Room: Your Personal Practice Repository</a></li>
<li><a href="./docs/05-working-with-issues.html">Working with Issues</a></li>
<li><a href="./docs/06-working-with-pull-requests.html">Working with Pull Requests</a></li>
<li><a href="./docs/07-merge-conflicts.html">Merge Conflicts</a></li>
<li><a href="./docs/08-open-source-culture.html">Culture, Etiquette, and Community Standards</a></li>
<li><a href="./docs/09-labels-milestones-projects.html">Labels, Milestones, and Projects</a></li>
<li><a href="./docs/10-notifications-and-day-1-close.html">Notifications</a></li>
</ul>
</details>
<details>
<summary>Day 2 chapters</summary>
<ul>
<li><a href="./docs/11-vscode-interface.html">VS Code: Interface and Setup</a></li>
<li><a href="./docs/12-vscode-accessibility.html">VS Code: Accessibility Deep Dive</a></li>
<li><a href="./docs/13-how-git-works.html">How Git Works: The Mental Model</a></li>
<li><a href="./docs/14-git-in-practice.html">Git & Source Control in VS Code</a></li>
<li><a href="./docs/15-code-review.html">Code Review: PRs, Diffs, and Constructive Feedback</a></li>
<li><a href="./docs/16-github-copilot.html">GitHub Copilot</a></li>
<li><a href="./docs/17-issue-templates.html">Issue Templates</a></li>
<li><a href="./docs/18-fork-and-contribute.html">Fork and Contribute: The Open Source Workflow</a></li>
<li><a href="./docs/19-accessibility-agents.html">Accessibility Agents</a></li>
<li><a href="./docs/20-build-your-agent.html">Capstone Project: Contribute an Impactful Agent</a></li>
<li><a href="./docs/21-github-accessibility-and-open-source.html">GitHub Accessibility and Open Source at Scale</a></li>
<li><a href="./docs/22-what-comes-next.html">What Comes Next: Your Developer Journey</a></li>
</ul>
</details>
</section>
<section class="guided-section">
<h3>Appendices</h3>
<details>
<summary>Reference library</summary>
<ul>
<li><a href="./docs/appendix-a-glossary.html">Appendix A: GitHub Concepts & Glossary</a></li>
<li><a href="./docs/appendix-b-screen-reader-cheatsheet.html">Appendix B: Screen Reader Cheat Sheet</a></li>
<li><a href="./docs/appendix-c-markdown-reference.html">Appendix C: Markdown and GitHub Flavored Markdown - Complete Guide</a></li>
<li><a href="./docs/appendix-d-git-authentication.html">Appendix D: Git Authentication</a></li>
<li><a href="./docs/appendix-e-advanced-git.html">Appendix E: Advanced Git Operations</a></li>
<li><a href="./docs/appendix-f-git-security.html">Appendix F: Git Security for Contributors</a></li>
<li><a href="./docs/appendix-g-vscode-reference.html">Appendix G: VS Code Accessibility Reference</a></li>
<li><a href="./docs/appendix-h-github-desktop.html">Appendix H: GitHub Desktop</a></li>
<li><a href="./docs/appendix-i-github-cli.html">Appendix I: GitHub CLI Reference</a></li>
<li><a href="./docs/appendix-j-cloud-editors.html">Appendix J: GitHub Codespaces</a></li>
<li><a href="./docs/appendix-k-copilot-reference.html">Appendix K: Copilot Reference</a></li>
<li><a href="./docs/appendix-l-agents-reference.html">Appendix L: Accessibility Agents Reference</a></li>
<li><a href="./docs/appendix-m-accessibility-standards.html">Appendix M: Accessibility Standards Reference</a></li>
<li><a href="./docs/appendix-n-advanced-search.html">Appendix N: GitHub Advanced Search</a></li>
<li><a href="./docs/appendix-o-branch-protection.html">Appendix O: Branch Protection Rules and Repository Rulesets</a></li>
<li><a href="./docs/appendix-p-security-features.html">Appendix P: GitHub Security Features</a></li>
<li><a href="./docs/appendix-q-actions-workflows.html">Appendix Q: GitHub Actions and Workflows</a></li>
<li><a href="./docs/appendix-r-projects-deep-dive.html">Appendix R: GitHub Projects Deep Dive</a></li>
<li><a href="./docs/appendix-s-releases-tags-insights.html">Appendix S: Releases, Tags, and Repository Insights</a></li>
<li><a href="./docs/appendix-t-community-and-social.html">Appendix T: Community and Social</a></li>
<li><a href="./docs/appendix-u-discussions-and-gists.html">Appendix U: Discussions and Gists</a></li>
<li><a href="./docs/appendix-v-github-mobile.html">Appendix V: GitHub Mobile</a></li>
<li><a href="./docs/appendix-w-github-pages.html">Appendix W: Publishing with GitHub Pages</a></li>
<li><a href="./docs/appendix-x-resources.html">Appendix X: Resources</a></li>
<li><a href="./docs/appendix-y-workshop-materials.html">Appendix Y: Accessing and Downloading Workshop Materials</a></li>
<li><a href="./docs/appendix-z-github-skills.html">Appendix Z: GitHub Skills - Complete Course Catalog</a></li>
<li><a href="./docs/appendix-aa-agent-installation-setup.html">Appendix AA: Agent Installation & Setup Across All Platforms</a></li>
<li><a href="./docs/appendix-ab-advanced-agent-patterns.html">Appendix AB: Advanced Agent Patterns & Skills</a></li>
<li><a href="./docs/appendix-ac-document-developer-tools.html">Appendix AC: Document & Developer Tool Agents</a></li>
</ul>
</details>
</section>
<section class="guided-section">
<h3>Challenge Lab</h3>
<ul>
<li><a href="./docs/CHALLENGES.html">Challenge Hub</a></li>
<li><a href="./work.html">Issue-Style Challenge Walkthrough</a></li>
<li><a href="./docs/17-issue-templates.html">Issue Template Deep Dive</a></li>
</ul>
</section>
<section class="guided-section">
<h3>External Resources</h3>
<ul>
<li><a href="https://lp.csedesigns.com/ggg/PODCASTS.html">Podcast Episodes <span class="guided-external">(external)</span></a></li>
<li><a href="https://lp.csedesigns.com/ggg/feed.xml">RSS Feed <span class="guided-external">(external)</span></a></li>
</ul>
</section>
<section class="guided-section">
<h3>Get Help</h3>
<ul>
<li><a href="https://github.com/Community-Access/support">Support Hub <span class="guided-external">(external)</span></a></li>
</ul>
</section>
</nav>
</aside>
<main id="main-content" class="markdown-body page-main">
<nav class="quick-jumps" aria-label="Quick jumps">
<h2 class="quick-jumps-title">Quick Jumps</h2>
<ul class="quick-jumps-list">
<li><a href="#course-content">Jump to course content</a></li><li><a href="#main-content">Jump to main content top</a></li><li><a href="#on-this-page">Jump to on-page sections</a></li><li><a href="./docs/CHALLENGES.html">Open challenge hub</a></li><li><a href="./work.html">Open issue-style challenge walkthrough</a></li>
</ul>
</nav>
<nav id="on-this-page" class="onpage-nav" aria-label="On this page">
<h2 class="onpage-title">On This Page</h2>
<ul class="onpage-list">
<li class="onpage-item"><a href="#table-of-contents">Table of Contents</a></li>
<li class="onpage-item"><a href="#1-who-this-is-for">1. Who This Is For</a></li>
<li class="onpage-item"><a href="#2-what-kinds-of-contributions-are-welcome">2. What Kinds of Contributions Are Welcome</a></li>
<li class="onpage-item onpage-sub"><a href="#documentation-improvements">Documentation Improvements</a></li>
<li class="onpage-item onpage-sub"><a href="#issues-and-bug-reports">Issues and Bug Reports</a></li>
<li class="onpage-item onpage-sub"><a href="#workshop-materials">Workshop Materials</a></li>
<li class="onpage-item onpage-sub"><a href="#what-we-are-not-looking-for-right-now">What We Are Not Looking For Right Now</a></li>
<li class="onpage-item"><a href="#3-before-you-start---fork-and-clone">3. Before You Start - Fork and Clone</a></li>
<li class="onpage-item onpage-sub"><a href="#account-security">Account security</a></li>
<li class="onpage-item onpage-sub"><a href="#fork-the-repository">Fork the Repository</a></li>
<li class="onpage-item onpage-sub"><a href="#clone-your-fork">Clone Your Fork</a></li>
<li class="onpage-item onpage-sub"><a href="#add-the-upstream-remote">Add the Upstream Remote</a></li>
<li class="onpage-item"><a href="#4-contribution-workflow---step-by-step">4. Contribution Workflow - Step by Step</a></li>
<li class="onpage-item onpage-sub"><a href="#step-1---sync-with-upstream">Step 1 - Sync with Upstream</a></li>
<li class="onpage-item onpage-sub"><a href="#step-2---create-a-focused-branch">Step 2 - Create a Focused Branch</a></li>
<li class="onpage-item onpage-sub"><a href="#step-3---make-your-changes">Step 3 - Make Your Changes</a></li>
<li class="onpage-item onpage-sub"><a href="#step-4---commit-your-changes">Step 4 - Commit Your Changes</a></li>
<li class="onpage-item onpage-sub"><a href="#step-5---push-to-your-fork">Step 5 - Push to Your Fork</a></li>
<li class="onpage-item onpage-sub"><a href="#step-6---open-a-pull-request">Step 6 - Open a Pull Request</a></li>
<li class="onpage-item"><a href="#5-writing-and-style-guidelines">5. Writing and Style Guidelines</a></li>
<li class="onpage-item onpage-sub"><a href="#voice">Voice</a></li>
<li class="onpage-item onpage-sub"><a href="#structure">Structure</a></li>
<li class="onpage-item onpage-sub"><a href="#keyboard-shortcuts">Keyboard Shortcuts</a></li>
<li class="onpage-item onpage-sub"><a href="#links">Links</a></li>
<li class="onpage-item"><a href="#6-accessibility-requirements">6. Accessibility Requirements</a></li>
<li class="onpage-item onpage-sub"><a href="#heading-structure">Heading Structure</a></li>
<li class="onpage-item onpage-sub"><a href="#links-and-references">Links and References</a></li>
<li class="onpage-item onpage-sub"><a href="#images-and-media">Images and Media</a></li>
<li class="onpage-item onpage-sub"><a href="#tables">Tables</a></li>
<li class="onpage-item onpage-sub"><a href="#code-blocks">Code Blocks</a></li>
<li class="onpage-item"><a href="#7-html-documentation-build-system">7. HTML Documentation Build System</a></li>
<li class="onpage-item onpage-sub"><a href="#how-it-works">How It Works</a></li>
<li class="onpage-item onpage-sub"><a href="#local-development">Local Development</a></li>
<li class="onpage-item onpage-sub"><a href="#html-features">HTML Features</a></li>
<li class="onpage-item onpage-sub"><a href="#what-you-need-to-know-when-contributing">What You Need to Know When Contributing</a></li>
<li class="onpage-item onpage-sub"><a href="#troubleshooting">Troubleshooting</a></li>
<li class="onpage-item"><a href="#8-screen-reader-guidance-for-commands-in-this-document">8. Screen Reader Guidance for Commands in This Document</a></li>
<li class="onpage-item onpage-sub"><a href="#nvda">NVDA</a></li>
<li class="onpage-item onpage-sub"><a href="#jaws">JAWS</a></li>
<li class="onpage-item onpage-sub"><a href="#voiceover-macos">VoiceOver (macOS)</a></li>
<li class="onpage-item"><a href="#9-submitting-your-pull-request">9. Submitting Your Pull Request</a></li>
<li class="onpage-item onpage-sub"><a href="#pr-template">PR Template</a></li>
<li class="onpage-item onpage-sub"><a href="#pr-title-format">PR Title Format</a></li>
<li class="onpage-item onpage-sub"><a href="#size-guideline">Size Guideline</a></li>
<li class="onpage-item"><a href="#10-what-happens-after-you-submit">10. What Happens After You Submit</a></li>
<li class="onpage-item"><a href="#11-questions-and-discussion">11. Questions and Discussion</a></li>
<li class="onpage-item"><a href="#authoritative-sources">Authoritative Sources</a></li>
<li class="onpage-item onpage-sub"><a href="#section-level-source-map">Section-Level Source Map</a></li>
</ul>
</nav>
<div id="course-content"><p><strong>Table: Keyboard shortcut for focusing search in different screen readers</strong></p>
<h1 id="contributing-to-this-workshop-repository">Contributing to This Workshop Repository</h1>
<p>Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome.</p>
<p>This guide covers contributing to <strong>this workshop learning repository</strong>. For contributing to Accessibility Agents itself (the project you work on during Day 2), see <a href="https://github.com/community-access/accessibility-agents/blob/main/CONTRIBUTING.md">Accessibility Agents' CONTRIBUTING.md</a>.</p>
<h2 id="table-of-contents">Table of Contents</h2>
<ol>
<li><a href="#1-who-this-is-for">Who This Is For</a></li>
<li><a href="#2-what-kinds-of-contributions-are-welcome">What Kinds of Contributions Are Welcome</a></li>
<li><a href="#3-before-you-start--fork-and-clone">Before You Start - Fork and Clone</a></li>
<li><a href="#4-contribution-workflow--step-by-step">Contribution Workflow - Step by Step</a></li>
<li><a href="#5-writing-and-style-guidelines">Writing and Style Guidelines</a></li>
<li><a href="#6-accessibility-requirements">Accessibility Requirements</a></li>
<li><a href="#7-html-documentation-build-system">HTML Documentation Build System</a></li>
<li><a href="#8-screen-reader-guidance-for-commands-in-this-document">Screen Reader Guidance for Commands in This Document</a></li>
<li><a href="#9-submitting-your-pull-request">Submitting Your Pull Request</a></li>
<li><a href="#10-what-happens-after-you-submit">What Happens After You Submit</a></li>
<li><a href="#11-questions-and-discussion">Questions and Discussion</a></li>
</ol>
<h2 id="1-who-this-is-for">1. Who This Is For</h2>
<p><strong>Workshop participants:</strong> You have already completed the contribution workflow during the workshop. This repository is an excellent first contribution target for applying what you practiced.</p>
<p><strong>Educators and facilitators:</strong> You are welcome to fork the entire repository and adapt the materials for your own workshop program. Attribution is required under the CC BY 4.0 license - please include a credit line and link to the original repository.</p>
<p><strong>Accessibility practitioners:</strong> If you have domain expertise in a particular screen reader or assistive technology and notice something that is incorrect or incomplete, please open an issue or submit a correction. Your expertise is exactly what this documentation needs.</p>
<p><strong>People who find bugs:</strong> A broken link, a command that has stopped working, an exercise that cannot be completed - all of these are legitimate bugs. Open an issue the same way you would for any software project.</p>
<h2 id="2-what-kinds-of-contributions-are-welcome">2. What Kinds of Contributions Are Welcome</h2>
<h3 id="documentation-improvements">Documentation Improvements</h3>
<ul>
<li><strong>Corrections:</strong> Wrong keyboard shortcut, screen reader command that has changed, broken external link, outdated UI description</li>
<li><strong>Clarity:</strong> A step that was confusing, an assumption that left someone behind, a paragraph that should be two</li>
<li><strong>Gaps:</strong> A common question that the documentation does not answer, an exercise step that was skipped</li>
<li><strong>New content:</strong> An additional exercise, a section about a tool or workflow not yet covered, a translation</li>
</ul>
<h3 id="issues-and-bug-reports">Issues and Bug Reports</h3>
<ul>
<li>A command in the workshop exercises that does not work as described</li>
<li>A screen reader behavior that differs from what the documentation says</li>
<li>A broken link or missing image</li>
<li>An exercise that assumes knowledge introduced later in the workshop</li>
</ul>
<h3 id="workshop-materials">Workshop Materials</h3>
<ul>
<li>New exercises that reinforce a concept</li>
<li>Facilitator notes based on running a session</li>
<li>Timing adjustments based on real session experience</li>
<li>Alternative approaches for participants on different operating systems</li>
</ul>
<h3 id="what-we-are-not-looking-for-right-now">What We Are Not Looking For Right Now</h3>
<ul>
<li>Rewriting the complete voice or structure of the workshop - if you have large-scale ideas, open a discussion first</li>
<li>Adding content about tools or platforms not currently mentioned in the workshop</li>
<li>Automated link-checking or content generation without human review</li>
</ul>
<h2 id="3-before-you-start---fork-and-clone">3. Before You Start - Fork and Clone</h2>
<p>You learned this workflow during the workshop. Here it is again as a reference.</p>
<h3 id="account-security">Account security</h3>
<p>Security: We strongly recommend enabling Two-Factor Authentication (2FA) on your GitHub account. If you cannot enable 2FA, add an SSH key or create a Personal Access Token (PAT) with <code>repo</code> scope before contributing. If you need help, contact the workshop organizers.</p>
<h3 id="fork-the-repository">Fork the Repository</h3>
<ol>
<li>Navigate to the workshop repository on GitHub</li>
<li>Activate the <strong>Fork</strong> button (top right of the repository page)</li>
<li>Select your account as the fork destination</li>
<li>Wait for the fork to complete - you will be redirected to your copy</li>
</ol>
<p><strong>Screen reader users:</strong></p>
<ul>
<li>NVDA / JAWS: Navigate by button (<code>B</code>) to find "Fork"</li>
<li>VoiceOver: <code>VO+Right Arrow</code> to find "Fork" button, <code>VO+Space</code> to activate</li>
</ul>
<h3 id="clone-your-fork">Clone Your Fork</h3>
<pre><code class="hljs language-bash">git <span class="hljs-built_in">clone</span> https://github.com/[your-username]/[workshop-repo-name].git
<span class="hljs-built_in">cd</span> [workshop-repo-name]</code></pre>
<h3 id="add-the-upstream-remote">Add the Upstream Remote</h3>
<p>This keeps your fork synchronized with the original repository:</p>
<pre><code class="hljs language-bash">git remote add upstream https://github.com/[original-owner]/[workshop-repo-name].git</code></pre>
<p>Verify both remotes are configured:</p>
<pre><code class="hljs language-bash">git remote -v</code></pre>
<p>Expected output:</p>
<pre><code class="hljs">origin <span class="hljs-link">https://github.com/</span>[<span class="hljs-string">your-username</span>]/[workshop-repo-name].git (fetch)
origin <span class="hljs-link">https://github.com/</span>[<span class="hljs-string">your-username</span>]/[workshop-repo-name].git (push)
upstream <span class="hljs-link">https://github.com/</span>[<span class="hljs-string">original-owner</span>]/[workshop-repo-name].git (fetch)
upstream <span class="hljs-link">https://github.com/</span>[<span class="hljs-string">original-owner</span>]/[workshop-repo-name].git (push)</code></pre>
<h2 id="4-contribution-workflow---step-by-step">4. Contribution Workflow - Step by Step</h2>
<p>This is the same workflow you practiced during the workshop, applied to a real contribution.</p>
<h3 id="step-1---sync-with-upstream">Step 1 - Sync with Upstream</h3>
<p>Always start from a current copy of the main branch:</p>
<pre><code class="hljs language-bash">git checkout main
git fetch upstream
git merge upstream/main
git push origin main</code></pre>
<h3 id="step-2---create-a-focused-branch">Step 2 - Create a Focused Branch</h3>
<p>One issue or topic per branch. Branch names should describe the change:</p>
<pre><code class="hljs language-bash">git checkout -b fix-nvda-shortcut-section-05
git checkout -b add-exercise-03-alternative-macos
git checkout -b update-broken-links-resources</code></pre>
<h3 id="step-3---make-your-changes">Step 3 - Make Your Changes</h3>
<p>Edit the file or files. Limit your changes to what is described in your branch name. Unrelated improvements belong in separate branches and separate pull requests.</p>
<p><strong>In VS Code:</strong></p>
<ol>
<li>Open the file in the Explorer (<code>Ctrl+Shift+E</code>)</li>
<li>Make your edits</li>
<li>Save (<code>Ctrl+S</code>)</li>
</ol>
<p><strong>In the GitHub web editor:</strong></p>
<ol>
<li>Navigate to the file</li>
<li>Activate the pencil icon (Edit this file)</li>
<li>Make your changes</li>
<li>Use "Commit changes" to save directly to your branch</li>
</ol>
<h3 id="step-4---commit-your-changes">Step 4 - Commit Your Changes</h3>
<p>Write a commit message that a future contributor can read and understand without context:</p>
<pre><code class="hljs language-bash">git add docs/05-working-with-issues.md
git commit -m <span class="hljs-string">"fix: correct NVDA virtual cursor toggle shortcut in Section 3
The documented shortcut was NVDA+Space which is correct for switching
between browse and focus mode, but the exercise called it 'reading mode'
which is not a term NVDA uses. Updated to match NVDA's own terminology."</span></code></pre>
<p><strong>Commit message format:</strong></p>
<pre><code class="hljs">type: <span class="hljs-keyword">short</span> summary (under <span class="hljs-number">72</span> <span class="hljs-keyword">characters</span>)
Optional longer explanation <span class="hljs-keyword">of</span> why <span class="hljs-keyword">the</span> change was made, <span class="hljs-keyword">not</span> just what
changed. What problem does this solve? What was wrong <span class="hljs-keyword">before</span>?</code></pre>
<p>Types: <code>fix</code>, <code>docs</code>, <code>exercise</code>, <code>style</code>, <code>chore</code></p>
<h3 id="step-5---push-to-your-fork">Step 5 - Push to Your Fork</h3>
<pre><code class="hljs language-bash">git push origin fix-nvda-shortcut-section-05</code></pre>
<h3 id="step-6---open-a-pull-request">Step 6 - Open a Pull Request</h3>
<ol>
<li>Navigate to your fork on GitHub</li>
<li>A banner should appear: "Compare & pull request" - activate it</li>
<li>If no banner appears: Activate the <strong>Pull requests</strong> tab → <strong>New pull request</strong> → change the compare branch to your branch</li>
<li>Fill in the PR template (see below)</li>
<li>Submit</li>
</ol>
<h2 id="5-writing-and-style-guidelines">5. Writing and Style Guidelines</h2>
<h3 id="voice">Voice</h3>
<ul>
<li><strong>Imperative mood for instructions:</strong> "Navigate to the Issues tab" not "You should navigate to the Issues tab"</li>
<li><strong>Present tense:</strong> "The button opens a dialog" not "The button will open a dialog"</li>
<li><strong>Specific:</strong> Name the exact shortcut, exact menu item, exact element to look for - do not say "click the appropriate option"</li>
<li><strong>Screen reader aware:</strong> Include landmark context, not just visual position ("the Save button in the dialog footer" not "the blue button on the right")</li>
</ul>
<h3 id="structure">Structure</h3>
<ul>
<li>Use heading levels consistently - H2 for major sections, H3 for subsections, H4 sparingly</li>
<li>Use numbered lists for sequential steps - the order matters and participants need to count steps</li>
<li>Use bulleted lists for options, items where order is unimportant</li>
<li>Use code blocks (<code>```</code>) for all commands, keyboard shortcuts in context, and file paths</li>
<li>Inline code (<code>``</code>) for short references to a key name, command name, or file name</li>
</ul>
<h3 id="keyboard-shortcuts">Keyboard Shortcuts</h3>
<p>Format all keyboard shortcuts in a table when listing more than two:</p>
<table>
<thead>
<tr>
<th scope="col">Action</th>
<th scope="col">NVDA</th>
<th scope="col">JAWS</th>
<th scope="col">VoiceOver</th>
</tr>
</thead>
<tbody><tr>
<td>Focus search</td>
<td><code>/</code></td>
<td><code>/</code></td>
<td><code>/</code></td>
</tr>
</tbody></table>
<p>When mentioning a single shortcut inline: use backticks - <code>NVDA+F7</code></p>
<h3 id="links">Links</h3>
<ul>
<li>Link text should describe the destination - not "click here" or "this guide"</li>
<li>Good: <code>[NVDA User Guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html)</code></li>
<li>Bad: <code>[click here](https://www.nvaccess.org/files/nvda/documentation/userGuide.html)</code></li>
</ul>
<h2 id="6-accessibility-requirements">6. Accessibility Requirements</h2>
<p>Every document in this repository is used by screen reader users. Accessibility is not a nice-to-have - it is the primary requirement. All contributions must meet the following:</p>
<h3 id="heading-structure">Heading Structure</h3>
<ul>
<li>Every heading must be in-sequence (no skipping from H2 to H4)</li>
<li>Every document must have exactly one H1 (<code>#</code>) - the page title</li>
<li>Headings must accurately describe the content they introduce</li>
</ul>
<h3 id="links-and-references">Links and References</h3>
<ul>
<li>No bare URLs in running text - always use descriptive link text</li>
<li>Exception: the Resources document may list URLs in table columns labeled "URL" for copy-paste use</li>
</ul>
<h3 id="images-and-media">Images and Media</h3>
<ul>
<li>Every image requires meaningful alt text</li>
<li>Alt text describes what the image shows, not just its label</li>
<li>Decorative-only images (rare in documentation) may use empty alt <code>alt=""</code></li>
<li>This workshop avoids screenshots of UI because screen reader users cannot use them - prefer text descriptions and keyboard instructions</li>
</ul>
<h3 id="tables">Tables</h3>
<ul>
<li>Every table must have a header row using <code>|---|</code> separator syntax in Markdown</li>
<li>Table headers must be meaningful and concise</li>
<li>Avoid merged cells - Markdown tables do not support them, and they create complex reading order for screen readers</li>
</ul>
<h3 id="code-blocks">Code Blocks</h3>
<ul>
<li>All terminal commands use fenced code blocks with language specified (<code>```bash</code>)</li>
<li>Inline code for short references uses single backticks</li>
<li>Commands that produce output should show the expected output separately, labeled</li>
</ul>
<h2 id="7-html-documentation-build-system">7. HTML Documentation Build System</h2>
<p>This repository maintains HTML versions of all Markdown files. The HTML is built locally and committed alongside the Markdown source, so both formats are always in sync.</p>
<h3 id="how-it-works">How It Works</h3>
<p><strong>Local build, committed output:</strong></p>
<ul>
<li>You edit <code>.md</code> files, then run <code>npm run build:html</code> before committing</li>
<li>Both the Markdown changes and the updated <code>html/</code> output are committed together</li>
<li>There is no CI pipeline - the build is your responsibility before pushing</li>
</ul>
<p><strong>What gets converted:</strong></p>
<ul>
<li>All markdown files in <code>docs/</code></li>
<li>All markdown files in <code>learning-room/</code></li>
<li>Root level markdown files (README.md, CONTRIBUTING.md, etc.)</li>
</ul>
<h3 id="local-development">Local Development</h3>
<p>You can build HTML files locally to preview your changes before pushing:</p>
<pre><code class="hljs language-bash"><span class="hljs-comment"># Install dependencies (first time only)</span>
npm install
<span class="hljs-comment"># Generate HTML files once</span>
npm run build:html
<span class="hljs-comment"># Watch mode - rebuilds HTML automatically when you save markdown files</span>
npm run watch:html
<span class="hljs-comment"># Clean generated HTML</span>
npm run clean</code></pre>
<p>Generated HTML files will be in the <code>html/</code> directory with the same folder structure as the source markdown files.</p>
<h3 id="html-features">HTML Features</h3>
<p>The generated documentation includes:</p>
<ul>
<li><strong>GitHub-flavored styling</strong> - familiar appearance for GitHub users</li>
<li><strong>Syntax highlighting</strong> for code blocks</li>
<li><strong>Responsive design</strong> - works on mobile and desktop</li>
<li><strong>Accessible markup</strong> - proper ARIA labels, semantic HTML, keyboard navigation</li>
<li><strong>Breadcrumb navigation</strong> - easy to return to home</li>
<li><strong>High contrast mode support</strong> - respects user preferences</li>
</ul>
<h3 id="what-you-need-to-know-when-contributing">What You Need to Know When Contributing</h3>
<p><strong>Build before committing:</strong>
After editing any <code>.md</code> file, run <code>npm run build:html</code> and include the updated <code>html/</code> files in your commit. A typical commit workflow:</p>
<pre><code class="hljs language-bash"><span class="hljs-comment"># Edit your .md files, then:</span>
npm run build:html
git add -A
git commit -m <span class="hljs-string">"docs: update chapter 6 and rebuild HTML"</span></code></pre>
<p><strong>Testing the HTML locally (optional):</strong>
If you want to verify how your Markdown will look in HTML before committing:</p>
<ol>
<li>Run <code>npm install</code> (first time only)</li>
<li>Run <code>npm run build:html</code></li>
<li>Open files in <code>html/</code> directory in your browser</li>
</ol>
<p><strong>HTML files in the repository:</strong>
The <code>html/</code> directory is committed to the repository so that:</p>
<ul>
<li>Documentation can be browsed directly from the repository</li>
<li>HTML files are version-controlled alongside their Markdown source</li>
<li>GitHub Pages can serve the documentation without a build step</li>
</ul>
<h3 id="troubleshooting">Troubleshooting</h3>
<p><strong>"npm: command not found"</strong>
You need to install Node.js first. Download from the <a href="https://nodejs.org/">Node.js download page</a> (LTS version recommended).</p>
<p><strong>Build errors:</strong></p>
<ul>
<li>Ensure all markdown files have valid syntax</li>
<li>Check that code blocks use proper fence syntax (<code>```</code>)</li>
<li>Look for unclosed brackets or parentheses in links</li>
</ul>
<h2 id="8-screen-reader-guidance-for-commands-in-this-document">8. Screen Reader Guidance for Commands in This Document</h2>
<p>If you are reviewing this repository using a screen reader, here are the relevant reading patterns.</p>
<h3 id="nvda">NVDA</h3>
<ul>
<li><strong>Table navigation:</strong> <code>T</code> to reach the table, then <code>Ctrl+Alt+Arrow Keys</code> to navigate cells</li>
<li><strong>Code blocks</strong> are read as preformatted text. NVDA reads the content character-by-character if you need to copy a command - use <code>NVDA+F8</code> to switch to flat review, then <code>NVDA+C</code> to copy a line</li>
<li><strong>Headings:</strong> <code>H</code> to jump between headings when in browse mode</li>
</ul>
<h3 id="jaws">JAWS</h3>
<ul>
<li><strong>Table navigation:</strong> <code>T</code> to reach the table, <code>Ctrl+Alt+Arrow Keys</code> for cells</li>
<li><strong>Code blocks:</strong> <code>Insert+F5</code> (forms list) will not find code elements - navigate with cursor keys</li>
<li><strong>Headings:</strong> <code>H</code> forward, <code>Shift+H</code> backward</li>
</ul>
<h3 id="voiceover-macos">VoiceOver (macOS)</h3>
<ul>
<li><strong>Table navigation:</strong> <code>VO+Right Arrow</code> through rows, <code>VO+Cmd+Right Arrow</code> through columns</li>
<li><strong>Code blocks</strong> in Markdown renderers on GitHub: navigate with <code>VO+Right Arrow</code>; activate "Select All" (<code>Cmd+A</code>) then "Copy" (<code>Cmd+C</code>) to copy a block</li>
<li><strong>Heading navigation with Rotor:</strong> <code>VO+U</code>, then left-right to select "Headings", then up-down to navigate</li>
</ul>
<h2 id="9-submitting-your-pull-request">9. Submitting Your Pull Request</h2>
<h3 id="pr-template">PR Template</h3>
<p>When you open a pull request, fill in the template that appears. If no template appears, include:</p>
<pre><code class="hljs language-markdown"><span class="hljs-section">## What does this change?</span>
<!-- One or two sentences describing the change -->
<span class="hljs-section">## Why?</span>
<!-- What problem does this fix or what gap does it address? -->
<span class="hljs-section">## How to test / review</span>
<!-- What should a reviewer look at? Where is the change? -->
<span class="hljs-section">## Checklist</span>
<span class="hljs-bullet">-</span> [ ] Heading levels are in sequence (no skips)
<span class="hljs-bullet">-</span> [ ] All links use descriptive text (no bare URLs in running text)
<span class="hljs-bullet">-</span> [ ] Command examples are in fenced code blocks
<span class="hljs-bullet">-</span> [ ] Tables have header rows
<span class="hljs-bullet">-</span> [ ] Spelling and grammar reviewed</code></pre>
<h3 id="pr-title-format">PR Title Format</h3>
<pre><code class="hljs"><span class="hljs-symbol">fix:</span> correct JAWS shortcut for PR review <span class="hljs-keyword">in</span> Section <span class="hljs-number">3</span>
<span class="hljs-symbol">docs:</span> <span class="hljs-keyword">add</span> alternative macOS exercise for Section <span class="hljs-number">6</span>
<span class="hljs-symbol">exercise:</span> <span class="hljs-keyword">add</span> bonus challenge for notifications day <span class="hljs-number">2</span></code></pre>
<h3 id="size-guideline">Size Guideline</h3>
<p>Small, focused pull requests are reviewed faster and merged sooner. If you have multiple unrelated improvements, submit them as separate pull requests.</p>
<h2 id="10-what-happens-after-you-submit">10. What Happens After You Submit</h2>
<ol>
<li><strong>A maintainer reviews your PR</strong> - typically within a few days for documentation changes</li>
<li><strong>You may receive review comments</strong> - these are not rejections; they are part of the collaboration</li>
<li><strong>You can add commits to the same branch</strong> to respond to feedback - GitHub adds them to the open PR automatically</li>
<li><strong>Once approved</strong>, a maintainer will merge the PR</li>
<li><strong>Your name is in the commit history</strong> of the repository - that is the permanent record of your contribution</li>
</ol>
<p>If two weeks pass with no response, feel free to leave a comment on the PR to check in.</p>
<h2 id="11-questions-and-discussion">11. Questions and Discussion</h2>
<p><strong>Before opening an issue:</strong> Search existing issues and discussions to see whether the question has already been raised.</p>
<p><strong>For documentation discussions:</strong> Open a GitHub Discussion (if enabled) or an Issue labeled <code>question</code></p>
<p><strong>For urgent issues with the workshop materials during a live event:</strong> Contact the facilitator directly</p>
<p><strong>For accessibility concerns:</strong> Tag your issue or comment with the <code>accessibility</code> label</p>
<p><em>Workshops run better when participants contribute back. Every correction, every clarification, every additional exercise makes this material stronger for everyone who comes after you. Your name in the commit history is not the end of your participation - it is the beginning.</em></p>
<p><em><a href="README.html">Back to README →</a> | <a href="docs/appendix-x-resources.html">Resources →</a> | <a href="CODE_OF_CONDUCT.html">Code of Conduct →</a></em></p>
<h2 id="authoritative-sources">Authoritative Sources</h2>
<p>Use these official references when you need the current source of truth for facts in this chapter.</p>
<ul>
<li><a href="https://docs.github.com/en">GitHub Docs, home</a></li>
<li><a href="https://github.blog/changelog/">GitHub Changelog</a></li>
</ul>
<h3 id="section-level-source-map">Section-Level Source Map</h3>
<p>Use this map to verify facts for each major section in this file.</p>
<ul>
<li><strong>1. Who This Is For:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a></li>
<li><strong>2. What Kinds of Contributions Are Welcome:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a></li>
<li><strong>3. Before You Start - Fork and Clone:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a>, <a href="https://docs.github.com/en/get-started/using-git/about-git">About Git</a>, <a href="https://docs.github.com/en/get-started/using-github/github-flow">GitHub flow</a>, <a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests">About pull requests</a></li>
<li><strong>4. Contribution Workflow - Step by Step:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a>, <a href="https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax">Workflow syntax for GitHub Actions</a>, <a href="https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions">Secure use reference for GitHub Actions</a>, <a href="https://github.blog/changelog/label/actions/">GitHub Actions changelog</a></li>
<li><strong>5. Writing and Style Guidelines:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a></li>
<li><strong>6. Accessibility Requirements:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a>, <a href="https://www.w3.org/WAI/standards-guidelines/wcag/">W3C Web Content Accessibility Guidelines (WCAG) 2 overview</a>, <a href="https://www.w3.org/WAI/tutorials/">WAI tutorials for accessible design patterns</a>, <a href="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a></li>
<li><strong>7. HTML Documentation Build System:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a></li>
<li><strong>8. Screen Reader Guidance for Commands in This Document:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a>, <a href="https://www.w3.org/WAI/standards-guidelines/wcag/">W3C Web Content Accessibility Guidelines (WCAG) 2 overview</a>, <a href="https://www.w3.org/WAI/tutorials/">WAI tutorials for accessible design patterns</a>, <a href="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a></li>
<li><strong>9. Submitting Your Pull Request:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a>, <a href="https://docs.github.com/en/get-started/using-git/about-git">About Git</a>, <a href="https://docs.github.com/en/get-started/using-github/github-flow">GitHub flow</a>, <a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests">About pull requests</a></li>
<li><strong>What does this change?:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a></li>
<li><strong>Why?:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a></li>
<li><strong>How to test / review:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a></li>
<li><strong>10. What Happens After You Submit:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a></li>
<li><strong>11. Questions and Discussion:</strong> <a href="https://docs.github.com/en">GitHub Docs, home</a>, <a href="https://github.blog/changelog/">GitHub Changelog</a>, <a href="https://docs.github.com/en/discussions">GitHub Discussions docs</a>, <a href="https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists">GitHub Gists docs</a></li>
</ul>
</div>
</main>
</div>
<footer role="contentinfo" class="site-footer">
<p><strong>GIT Going with GitHub</strong> - A workshop by <a href="https://community-access.org">Community Access</a></p>
<p><a href="https://github.com/community-access/git-going-with-github">View on GitHub</a> · <a href="https://community-access.org">community-access.org</a></p>
</footer>
<script>
(function() {
var key = 'gggLastVisitedPath';
var currentPath = window.location.pathname || '';
try {
if (currentPath) {
localStorage.setItem(key, currentPath);
}
} catch (e) {}
var resumeLink = document.getElementById('resume-link');
if (!resumeLink) return;
try {
var savedPath = localStorage.getItem(key);
if (savedPath && savedPath !== currentPath) {
resumeLink.hidden = false;
resumeLink.setAttribute('href', savedPath);
}
} catch (e) {}
})();
</script>
</body>
</html>