Github Primer

Return to Onboarding Homepage

Github basics

• Github is a public forum
  • What you post is public and searchable
  • Use a username and profile image that helps you feel safe
• If you do not know what github username you have associated with WCAG:
  • Go to https://www.w3.org/groups/wg/ag/participants/
  • Click on your name
  • Click on Edit Profile
  • Click on Connected Accounts

General guidance in writing on Github

• Please be considerate of others when writing on Github
  • Be polite
  • Assume positive intent
  • Positive Work Environment at W3C: Code of Ethics and Professional Conduct (CEPC)

• Use plain language guidelines
  • Write for your audience
  • Organize the information
  • Choose your words carefully
  • Be concise
  • Keep it conversational
  • Design for reading
  • Follow web standards

Links to practice content

We created practice content in Github for you to try out.

• Practice Issue - Use to try out commenting and reacting
• Practice Pull Request - Use to try out inline comments and small code changes
• Practice Discussion - Use to try out threaded discussions

Issues

What is it?

• A suggestion or concern
• May reference a PR or it may not
• Should include only 1 topic

To create an Issue:

1. Go to the issues tab (https://github.com/w3c/wcag3/issues)
2. Search by keywords to see if the issue already exists
3. Click “New Issue”
4. Add a concise but descriptive title
5. Add a description
   • Write the main point first
   • Supporting information afterwards

Creating an Issue Video

Pull Requests

What is it?

• Proposed change to the content
• Can be viewed as a diff (difference) between existing and proposed content
• Keep Pull Requests focused a single topic (editorial changes, updates to a single guideline, etc.)
  • The more diverse the PR, the more difficult it is to review and approve

Please request training if you want to create a PR

Commenting on Issues and Pull Requests

1. Scroll to the bottom of the conversation
2. Add your comments under the Write Tab
   • If you want to notify someone, use @ and select their username
3. You can format using the toolbar above the comment field
4. The Preview Tab allows you view the final content
5. Click the comment button to submit.
   • You can edit your comment after submitting by using the “Edit” under the comment options drop down menu (3 horizontal dots)

Commenting Video

Replying to comments with quote

1. Scroll to the comment you want to reference
2. Open the Comment Options Drop down Menu (3 horizontal dots)
3. Select Quote Reply

• This copies the content into a new comment.
• You can edit the content to call out only what you want to comment on and then add your thoughts

Replying to Comments Video

Reacting to Comments

1. Find the “Add or Remove Reactions” icon.
   • It looks like a gray smiley face in the left hand corner of the comment
2. Hit enter or click on it to open selections
3. Select the icon that indicates your opinion
4. Use:
   • Thumbs up - I generally agree. I may have comments but I am good with it moving forward
   • Thumbs down - I don’t generally agree, please comment with explanation and issue
   • Considering (eyes) - Have concerns, please comment with explanation. Denotes that you are cautiously agreeing but would like some changes
   • We are not using the other icons.
5. To remove your previous selection, click on the icon you selected next to the Add or Remove Reactions

Reacting to Comments Video

In-line comments and small code changes on Pull Requests

1. Go to Files Changed
2. Hover over or tab to an “Add line comment” button near the code you want to comment on.
   • This button looks like a plus sign and appears on hover or tab.
3. A comment field will appear. Complete this with comments specific to that line.
4. If you want to suggest a code change, click the "Add a Suggestion" button
   • The keyboard shortcut is cmd + g
5. Make the desired edits to that line of code
6. Use the "Add Single comment" button to suggest the change

Discussions

What is it?

• A threaded conversation about a larger question or topic

To start a discussion:

1. Go to the discussions tab (https://github.com/w3c/wcag3/discussions)
2. Click “New Discussion”
3. Use the “General” Discussion Category
4. Add a concise but descriptive title
5. Add a description of the topic
   • Main point or question first
   • Supporting information afterwards
6. Add your opinions about the topic as a comment in the discussion

Starting a Discussion Video

Using threaded discussions

• In Discussions, the ability to reply is directly below the comment.
• Once you place the focus in the reply box, you will receive a standard comment box
• Your reply will be place in a thread with the original comment.

Configuring your email

Turn off all emails

1. Click on your profile icon
2. Click on Settings
3. Click on Notifications
4. Uncheck Email on all Subscriptions

Turning Off all Github emails Video

Changing from Individual to digest emails

1. Click on your profile icon
2. Click on Settings
3. Click on Notifications
4. Go to Email Weekly Digest
5. Change to Weekly or Daily

Digest Emails Video

Managing Repository Preferences

1. Go to the repository and click Watch on bar across the top
2. Select whether you want to receive notifications for:
   • Issues you are participating on and all issues where someone mentions you
   • All activity in the repository
   • No notifications
   • Custom notifications (Issues, Pull Requests, Releases, Discussions, or Security Alerts)

Repository Settings Video

Unsubscribing to an Issue/PR/Discussion

1. Navigate to the issue you do not want to follow
   • If you are receiving emails, use the email to get to the correct issue
2. Click the Unsubscribe button on the right side under notifications

Unsubscribe Video